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What Is PHP? 

PHP is an open source, server-side, HTML-embedded web-scripting language that is compatible 
with all the major web servers (most notably Apache). PHP enables you to embed code fragments 
in normal HTML pages — code that is interpreted as your pages are served up to users. PHP also 
serves as a "glue" language, making it easy to connect your web pages to server-side databases. 



Why PHP? 

We devote nearly all of Chapter 1 to this question. The short answer is that it's free, it's open 
source, it's full featured, it's cross-platform, it's stable, it's fast, it's clearly designed, it's easy to 
learn, and it plays well with others. 



What's New in This Edition? 

This book is a new edition of the popular PHP Bible and PHP5 and MySQL Bible series. The book 
updates the elements from previous versions, where applicable, for PHP 6 and MySQL 6. 

New PHP 6 features 

Although much of PHP 5's functionality survives unchanged in PHP 6, there have been some 
changes. Among the ones we cover are: 

■ Unicode support, making internationalization easier 

■ Security enhancements such as removing safe_mode and register globals 

■ Enhancements to the object-oriented interfaces 

Who wrote the book? 

The first two editions were by Converse and Park, with a guest chapter by Dustin Mitchell and 
tech editing by Richard Lynch. For the third edition, Clark Morgan took on much of the revision 
work, with help from Converse and Park as well as from David Wall and Chris Cornell, who also 
contributed chapters and did technical editing. For this edition, Steve Suehring did revision work 
with Aaron Saray providing technical editing. 
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Whom This Book Is For 

This book is for anyone who wants to build web sites that exhibit more complex behavior than is 
possible with static HTML pages. Within that population, we had the following three particular 
audiences in mind: 

■ Web site designers who know HTML and want to move into creating dynamic web sites 

■ Experienced programmers (in C, Java, Perl, and so on) without web experience who want 
to quickly get up to speed in server-side web programming 

■ Web programmers who have used other server-side technologies (Active Server Pages, Java 
Server Pages, or ColdFusion, for example) and want to upgrade or simply add another tool 
to their kit 

We assume that the reader is familiar with HTML and has a basic knowledge of the workings of the 
web, but we do not assume much programming experience beyond that. To help save time for more 
experienced programmers, we include a number of notes and asides that compare PHP with other 
languages and indicate which chapters and sections may be safely skipped. Finally, see our appen- 
dixes, which offer specific advice for C programmers, ASP coders, and pure-HTML designers. 



This Book Is Not the Manual 

The PHP Documentation Group has assembled a great online manual, located at www .php.net and 
served up (of course) by PHP. This book is not that manual or even a substitute for it. We see the 
book as complementary to the manual and expect that you will want to go back and forth between 
them to some extent. 

In general, you'll find the online manual to be very comprehensive, covering all aspects and func- 
tions of the language, but inevitably without a great amount of depth in any one topic. By contrast, 
we have the leisure of zeroing in on aspects that are most used or least understood and give back- 
ground, explanations, and lengthy examples. 



How the Book Is Organized 

This book is divided into five parts, as the following sections describe. 

Part I: PHP: The Basics 

This part is intended to bring the reader up to speed on the most essential aspects of PHP, with com- 
plexities and abstruse features deferred to later parts. 

■ Chapters 1 through 3 provide an introduction to PHP and tell you what you need to know 
to get started. 
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■ Chapters 4 through 9 are a guide to the most central facets of PHP (with the exception of 
database interaction): the syntax, the data types, and the most basic built-in functions. 

■ Chapter 10 is a guide to the most common pitfalls of PHP programming. 

Part II: PHP and MySQL 

Part II is devoted both to MySQL and to PHP's interaction with MySQL. 

■ Chapters 11 and 12 provide a general orientation to web programming with SQL data- 
bases, including installation of MySQL. 

■ Chapter 13 covers Structured Query Language (SQL), and Chapter 14 covers database 
administration basics. 

■ Chapter 15 is devoted to PHP functions for MySQL. 

■ Chapters 16 and 17 are detailed, code-rich case studies of PHP/MySQL interactions. 

■ Chapters 18 and 19 provide tips and gotchas specific to PHP/MySQL work. 

Part III: Advanced Techniques 

In this part we cover more advanced features of PHP, usually as self-contained chapters, including 
object-oriented programming, session handling, exception handling, using cookies, and regular expres- 
sions. Chapter 31 is a tour of debugging techniques, and Chapter 32 discusses programming style. 

Part IV: Connections 

In this part we cover advanced techniques and features that involve PHP talking to other services, 
technologies, or large bodies of code. 

■ Chapters 33 through 36 cover PHP's interaction with other database technologies 
(PostgreSQL, Oracle, PDO, and SQLite). 

■ Chapters 37 through 42 cover self-contained topics: PHP and e-mail programs, combining 
PHP with JavaScript, integrating PHP and Java, PHP and XML, PHP-based Web services, 
and creating graphics with the g d image library. 

Part V: Case Studies 

Here we present three extended case studies that wrap together techniques from various early chapters. 

■ Chapter 43 takes you through the design and implementation of a weblog. 

■ Chapter 44 discusses a soup-to-nuts implementation of a novel trivia quiz game. 

■ Chapter 45 uses the gd image library to visualize data from a MySQL database. 
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Appendices 

At the end, we offer three "quick-start" appendixes, for use by people new to PHP but very famil- 
iar with either C (Appendix A), Perl (Appendix B), or pure HTML (Appendix C). If you are in any 
of these three situations, start with the appropriate appendix for an orientation to important dif- 
ferences and a guide to the book. Appendix (D) is a guide to important resources, web sites, and 
mailing lists for the PHP community. The final appendix (E) is information on the PEAR repository, 
which is no longer scheduled to be included in PHP 6. However, this information (from a previous 
edition of the book) may be helpful to someone maintaining a PHP site on an earlier version of PHP 
or one that uses PEAR. 



Conventions Used in This Book 

We use a monospaced font to indicate literal PHP code. Pieces of code embedded in lines of text look 
like this, while full code listing lines look as follows: 

p r i n t ( " t h 1 s " ) ; 

If the appearance of a PHP-created web page is crucial, we include a screenshot. If it is not, we 
show textual output of PHP in monospaced font. If we want to distinguish the PHP output as seen 
in your browser from the actual output of PHP (which your browser renders), we call the former 
browser output. 

If included in a code context, italics indicate portions that should be filled in appropriately, as 
opposed to being taken literally. In normal text, an italicized term means a possibly unfamiliar 
word or phrase. 



What the Icons Mean 



Icons similar to the following example are sprinkled liberally throughout the book. Their purpose is 
to visually set off certain important kinds of information. 



Tip icons indicate PHP tricks or techniques that may not be obvious and that enable you 
to accomplish something more easily or efficiently. 

Note icons usually provide additional information or clarification but can be safely 
ignored if you are not already interested. Notes in this book are often audience-specific, 
targeted to people who already know a particular programming language or technology. 



NOTE 



.... 



Caution icons indicate something that does not work as advertised, something that is eas- 
ily misunderstood or misused, or anything else that can get programmers into trouble. 



(■v jy CjCjCj^p P r ^ e use " 1 ' S ' con wnenevel ' related information is in a different chapter or section. 
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Why PHP and MySQL? 



This first chapter is an introduction to PHP, MySQL, and the interac- 
tion of the two. In it, we'll try to address some of the most common 
questions about these tools, such as "What are they?" and "How do 
they compare to similar technologies?" Most of the chapter is taken up with 
an enumeration of the many, many reasons to choose PHP, MySQL, or the 
two in tandem. If you're a techie looking for some ammunition to lob at your 
PHB ("Pointy-Haired Boss," for those who don't know the Dilbert cartoons) 
or a manager asking yourself what is this P-whatever thing your geeks keep 
whining to get, this chapter will provide some preliminary answers. 



IN THIS CHAPTER 



Understanding PHP and MySQL 

The benefits of using PHP 
and MySQL 



What Is PHP? 



PHP is the web development language written by and for web developers. 
PHP stands for PHP: Hypertext Preprocessor. The product was originally 
named Personal Home Page Tools, and many people still think that's what the 
acronym stands for, but as it expanded in scope, a new and more appropri- 
ate (albeit GNU-ishly recursive) name was selected by community vote. 
PHP is currently in its sixth major rewrite, called PHP6 or just plain PHP. 

PHP is a server-side scripting language, usually used to create web applica- 
tions in combination with a web server, such as Apache. PHP can also be 
used to create command-line scripts akin to Perl or shell scripts, but such 
use is much less common than PHP's use as a web language. 

Strictly speaking, PHP has nothing to do with layout, events, on-the-fly 
Document Object Model (DOM) manipulation, or really anything about the 
look and feel of a web page. In fact, most of what PHP does is invisible to 
the end user. Someone looking at a PHP page will not necessarily be able to 
tell that it was not written purely in Hypertext Markup Language (HTML), 
because the result of PHP is usually HTML. 
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What Is MySQL? 

MySQL (pronounced My Ess Q El) is an open source, SQL relational database management system 
(RDBMS) that is free for many uses (more detail on that later). Early in its history, MySQL occasion- 
ally faced opposition because of its lack of support for some core SQL constructs such as subselects 
and foreign keys. Ultimately, however, MySQL found a broad, enthusiastic user base for its liberal 
licensing terms, perky performance, and ease of use. Its acceptance was aided in part by the wide 
variety of other technologies such as PHP, Perl, Python, and the like that have encouraged its use 
through stable, well-documented modules and extensions. 

Databases are generally useful, perhaps the most consistently useful family of software products 
(the "killer product") in modern computing. Like many competing products, both free and com- 
mercial, MySQL isn't a database until you give it some structure and form. You might think of this 
as the difference between a database and an RDBMS (that is, RDBMS plus user requirements equal a 
database). 

There's lots more to say about MySQL, but then again, there's lots more space in which to say it. 



Deciding on a Web Application Platform 

There are many platforms upon which web applications can be built. This section compares PHP to 
a few other platforms and highlights some of PHP's and MySQL's strengths. 

Cost 

PHP is one of the "P's" in the popular LAMP stack. The LAMP stack refers to the popular combina- 
tion of Linux, Apache, MySQL, and PHP/Perl/Python that runs many web sites and powers many 
web applications. Many of the components of the LAMP stack are free, and PHP is no exception. 
PHP is free, as in there is no cost to develop in and run programs made with PHP. Though MySQL's 
license and costs have changed, you can obtain the Community Server edition for free. MySQL 
offers several levels of support contracts for their database server. More information can be obtained 
at www . my sql .com. Both PHP and MySQL run on a variety of platforms, including many variants 
of Linux, Microsoft Windows, and others. Running on an operating system such as Linux gives the 
opportunity for a completely free web application platform, with no up-front costs. 

Of course, when talking about software development and application platforms, the up-front cost of 
software licensing is only a portion of the total cost of ownership (TCO). Years of real-world experi- 
ence with Linux, Apache, MySQL, and PHP in production environments has proved that the total 
cost of maintaining these platforms is lower, many times much lower, than maintaining an infra- 
structure with proprietary, non-free software. 
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Ease of Use 

When compared to many other programming languages, PHP makes it easy to develop powerful 
web applications quickly (this is a blessing and a curse). Many of the most useful specific functions 
(such as those for opening a connection to an Oracle database or fetching e-mail from an Internet 
Message Access Protocol [IMAP] server) are predefined for you. A lot of complete scripts are waiting 
out there for you to look at as you're learning PHP. 

Most advanced PHP users (including most of the development team members) are diehard hand- 
coders. They tend to share certain gut-level, subcultural assumptions — for instance, that hand- 
written code is beautiful and clean and maximally browser-compatible and therefore the only way 
to go — that they do not hesitate to express in vigorous terms. The PHP community offers help and 
trades tips mostly by e-mail, and if you want to participate, you have to be able to parse plain-text 
source code with facility. Some WYSIWYG users occasionally ask list members to diagnose their 
problems by looking at their web pages instead of their source code, but this rarely ends well. 

That said, let us reiterate that PHP really is easy to learn and write, especially for those with a little 
bit of experience in a C-syntaxed programming language. It's just a little more involved than HTML. 
This small learning curve means that relatively inexperienced programmers can sometimes make 
mistakes that turn into large security issues. This is the curse of PHP. While this book has no spe- 
cific chapter dedicated to security, I feel that security needs to be applied at every layer, during every 
phase of programming. Therefore dedicating a single chapter would not do justice to the importance 
of web application security. 

If you have no relational database experience, or are coming from an environment such as Microsoft 
Access, MySQL's command-line interface and lack of implicit structure may at first seem a little 
daunting. MySQL has a few GUI (graphical user interface) tools to help work with databases. None 
of the GUI tools is a substitute for learning a little theory and employing good design practices, but 
that is a subject for another chapter. 

HTML-embeddedness 

PHP can be embedded within HTML. In other words, PHP pages are ordinary HTML pages that 
escape into PHP mode only when necessary. Here is an example: 

<HEAD> 

<TITLE>Example.com greet ing</TITLE> 

</HEAD> 

<B0DY> 

<P>Hello, 

<?php 

// We have now escaped into PHP mode. 

// Instead of static variables, the next three lines 

// could easily be database calls or even cookies; 

// or they could have been passed from a form. 

$f i rstname = ' Joyce ' ; 

$1 astname = ' Park ' ; 
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$title = 'Ms. ' ; 

echo "Ititle $lastname"; 

// OK, we are going back to HTML now. 

?> 

We know who you are! Your first name is < ? p h p echo 
$firstname; ?>.</P> 

<P>You are visiting our site at < ? p h p echo date('Y-m-d H : i : s ' ) ; 
?></P> 

<P>Here is a link to your account management page: <A 

HREF="http:/ /www .example. com/ a ccounts/<?php echo 

"$f i rstname$l astname" ; ?>/"><?php echo $firstname; ?>'s account 

management page</AX/P> 

</B0DY> 

</HTML> 

When a client requests this page, the web server preprocesses it. This means it goes through the 
page from top to bottom, looking for sections of PHP, which it will try to resolve. For one thing, the 
parser will suck up all assigned variables (marked by dollar signs) and try to plug them into later 
PHP commands (in this case, the echo function). If everything goes smoothly, the preprocessor will 
eventually return a normal HTML page to the client's browser, as shown in Figure 1-1. 



FIGURE 1-1 



A result of preprocessed PHP 



Ex a mple.com greeting -Mozilla (Build ID: 2OQ2G51O06) 



Fife Edrl View Go Bookmarks Tools Window Help Debug Qtk 



(^ |'V http M o e a IhosUsa nt_c a d e 'ch1 1 g i eeiing. p h p | |C\ Search! IMi 



Hello, Ms, Park . We know who yon are! Youi fust name is Joyce 

You are visiting oiu site at 2002-07-29 00:52:42 

Here is a link to your account management page: Joyce's account 
management page 



Document: Done (0.82 sees) 



If you peek at the source code from the client browser (select Source or Page Source from the View 
menu, it will look like this: 

<HEAD> 

<TITLE>Example.com greet ing</TITLE> 
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</HEAD> 
<BODY> 
<P>Hello, 
Ms. Park 

We know who you are! Your first name is Joyce. </P> 

<P>You are visiting our site at 2002-04-21 19 : 34 : 24</P> 

<P>Here is a link to your account management page: <A HREF="http: // 

www . exampl e . com/accounts / JoycePa rk/ "> Joyce ' s account management page</ 

AX/P> 

</B0DY> 

</HTML> 

This code is exactly the same as if you were to write the HTML by hand. So simple! 
The HTML-embeddedness of PHP has many helpful consequences: 

■ PHP can quickly be added to code produced by WYSIWYG editors. 

■ PHP lends itself to a division of labor between designers and programmers. 

■ Every line of HTML does not need to be rewritten in a programming language. 

■ PHP can reduce labor costs and increase efficiency because of its shallow learning curve 
and ease of use. 



Cross-platform compatibility 

PHP and MySQL run native on every popular flavor of Linux/Unix (including Mac OS X) and 
Microsoft Windows. A huge percentage of the world's Hypertext Transfer Protocol (HTTP) servers 
run on one of these two classes of operating systems. 

PHP is compatible with the leading web servers: Apache HTTP Server for Linux/Unix and Windows 
and Microsoft Internet Information Server. It also works with several lesser-known servers. Specific 
web server compatibility with MySQL is not required, since PHP will handle all the dirty work for you. 

Stability 

The word stable means two different things in this context: 

■ The server doesn't need to be rebooted or restarted often. 

■ The software doesn't change radically and incompatibly from release to release. 



To our advantage, both of these connotations apply to both MySQL and PHP. 

Apache Server is generally considered the most stable of major web servers, with a reputation for 
enviable uptime percentages. Most often, a server reboot isn't required for each setting change. PHP 
inherits this reliability; plus, its own implementation is solid yet lightweight. 
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PHP and MySQL are also both stable in the sense of feature stability. Their respective development 
teams have thus far enjoyed a clear vision of their project and refused to be distracted by every new 
fad and ill-thought-out user demand that comes along. Much of the effort goes into incremental per- 
formance improvements, communicating with more major databases, or adding better OOP support. 
In the case of MySQL, the addition of reasonable and expected new features has hit a rapid clip. For 
both PHP and MySQL, such improvements have rarely come at the expense of compatibility. 

Many extensions 

PHP makes it easy to communicate with other programs and protocols. The PHP development team 
seems committed to providing maximum flexibility to the largest number of users. 

Database connectivity is especially strong, with native-driver support for about 15 of the most popu- 
lar databases plus Open DataBase Connectivity (ODBC). In addition, PHP supports a large number 
of major protocols such as POP3, IMAP, and LDAP Earlier versions of PHP added support for Java 
and distributed object architectures (Component Object Model [COM] and Common Object Request 
Broker Architecture [CORBA]), making n-tier development a possibility for the first time, fully incor- 
porated GD graphics library and revamped Extensible Markup Language (XML) support with DOM 
and simpleXML. 

Fast feature development 

Users of proprietary web development technologies can sometimes be frustrated by the glacial speed 
at which new features are added to the official product standard to support emerging technologies. 
With PHP, this is not a problem. All it takes is one developer, a C compiler, and a dream to add 
important new functionality. This is not to say that the PHP team will accept every random contri- 
bution into the official distribution without community buy-in, but independent developers can and 
do distribute their own extensions that may later be folded into the main PHP package in more or 
less unitary form. For instance, Dan Libby's elegant xmlrpc-epi extension was adopted as part of the 
PHP distribution in version 4.1, a few months after it was first released as an independent package. 

PHP development is also constant and ongoing. Although there are clearly major inflection points, 
such as the transition between PHP4 and PHP5, these tend to be most important deep in the guts 
of the parser — people were actually working on major extensions throughout the transition period 
without critical problems. Furthermore, the PHP group subscribes to the open source philosophy 
of "release early, release often," which gives developers many opportunities to follow along with 
changes and report bugs. 

Not proprietary 

The history of the personal computer industry to date has largely been a chronicle of proprietary 
standards: attempts to establish them, clashes between them, their benefits and drawbacks for the 
consumer, and how they are eventually replaced with new standards. 
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In the past few years the Internet has demonstrated the great convenience of voluntary, standards- 
based, platform-independent compatibility. E-mail, for example, works so well because it enjoys a 
clear, firm standard to which every program on every platform must conform. New developments 
that break with the standard (for example, HTML-based e-mail stationery) are generally regarded as 
deviations, and their users find themselves having to bear the burdens of early adoption. 

Furthermore, customers (especially the big-fish businesses with large systems) are fed up with 
spending vast sums to conform to a proprietary standard only to have the market uptake not turn 
out as promised. Much of the current momentum toward XML and web services is driven by years 
of customer disappointment with Java RMI (Remote Method Invocation), CORBA, COM, and even 
older proprietary methods and data formats. 

Right now, software developers are in a period of experimentation and flux concerning proprietary 
versus open standards. Companies want to be sure that they can maintain profitability while adopt- 
ing open standards. There have been some major legal conflicts related to proprietary standards, 
which are still being resolved. These could eventually result in mandated changes to the codebase 
itself or even affect the futures of the companies involved. In the face of all this uncertainty, a grow- 
ing number of businesses are attracted to solutions that they know will not have these problems in 
the foreseeable future. 

PHP is in a position of maximum flexibility because it is, so to speak, antiproprietary. It is not tied 
to any one server operating system, unlike Active Server Pages. It is not tied to any proprietary 
cross-platform standard or middleware, as is Java Server Pages or ColdFusion. It is not tied to any 
one browser or implementation of a programming language or database. PHP isn't even doctrinaire 
about working only with other open source software. This independent but cooperative pragmatism 
should help PHP ride out the stormy seas that seem to lie ahead. 

Strong user communities 

PHP is developed and supported in a collaborative fashion by a worldwide community of users. 
Some animals (such as the core developers) are more equal than others, but that's hard to argue 
with, because they put in the most work, had the best ideas, and have managed to maintain civil 
relationships with the greatest number of other users. 

The main advantage for most new users is technical support without charge, without boundaries, 
and without the runaround. People on the mailing list are available 24/7/52 to answer your ques- 
tions, help debug your code, and listen to your gripes. The support is human and real. PHP commu- 
nity members might tell you to read the manual, take your question over to the appropriate database 
mailing list, or just stop your whining — but they'll never tell you to wipe your C drive and then 
charge you for the privilege. Often, they'll look at your code and tell you what you're doing wrong or 
even help you design an application from the ground up. 

As you become more comfortable with PHP, you may wish to contribute. Bug tracking, offering 
advice to others on the mailing lists, posting scripts to public repositories, editing documentation, 
and, of course, writing C code are all ways you can give back to the community. 
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MySQL, while open source licensed for non-redistributive uses, is somewhat less community driven 
in terms of its development. Nevertheless, it benefits from a growing community of users who are 
actively listened to by the development team. Rarely has a software project responded so vigorously 
to community demand, and the community of users can be extremely responsive to other users who 
need help. It's a point of pride with a lot of SQL gurus that they can write the complicated queries 
that get you the results you are looking for but had struggled with for days. In many cases, they'll 
help you for nothing more than the enduring, if small, fame that comes with the archived presence 
of their name on Google Groups. Lry comparing that with $100 per incident support. 



Summary 

PHP and MySQL, individually or together, aren't the panacea for every web development problem, 
but they present a lot of advantages. PHP is built by web developers for web developers and sup- 
ported by a large and enthusiastic community. MySQL is a powerful standards-compliant RDBMS 
that comes in at an extremely competitive price point, even more so if you qualify for free use. Both 
technologies are clear-cut cases of the community banding together to address its own needs. 
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Scripting Overview 



This chapter is about server-side scripting and its relationship to both 
static HTML and common client-side technologies. By the end, you 
can expect to gain a clear understanding of what kinds of things 
PHP can and cannot do for you, along with a general understanding of 
how it interacts with client-side code (JavaScript, Java applets, Flash, style 
sheets, and the like). 



Static HTML 



The most basic type of web page is a completely static, text-based one, writ- 
ten entirely in HTML. Take the simple HTML-only page that Figure 2-1 
shows as an example. 

The following example displays the source code for the web page shown in 
Figure 2-1: 

<!D0CTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 

"http://www.w3.org/TR/htinl4/strict.dtd"> 

<html > 

<head> 

<title>Selected Constellations</title> 

</head> 

<body> 

<hl>Constellations</hl> 
<ul > 

<1 i ><a href="Aqui 1 a . html ">Aqui la</a></li> 
<1 iXa href=" Bootes . html ">Bootes</aX/l i> 
<1 i ><a href="Cassiopeia. html ">Cassi ope ia</aX/li> 



IN THIS CHAPTER 



Understanding static and 
dynamic web pages 

Client-side versus server-side 
scripting 

An introduction to server-side 
scripting 
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<1 iXa 
<1 iXa 
<1 iXa 
<1 iXa 
<1 IXa 
<1 IXa 
<1 IXa 
<1 iXa 
<1 iXa 
<1 iXa 
<1 IXa 
<1 IXa 
<1 IXa 
<1 iXa 
<1 iXa 
</ul > 
</body> 
</html > 



href = 
href = 
href = 
href = 
href = 
href = 
href = 
h ref = 
h ref = 
h ref = 
href = 
href = 
href = 
href = 
href = 



Cy gnus, html ">Cygnus</aX/li> 
Deneb.html ">Deneb</aX/l i > 
Draco.html ">Draco</aX/l i> 
Gemi ni . html " >Gemi ni </aX/l i > 
Leo. html ">Leo</aX/l i> 
Libra.html ">Li bra</aX/l i> 
Lynx . html " > Ly nx</aX/l i > 
Or i on. html ">0rion</aX/l i> 
Pegasus.html ">Pegasus</aX/l i> 
Perseus, html ">Perseus</aX/l i> 
Pi sees. html ">Pisces</aX/li> 
Taurus, html ">Taurus</aX/li> 
Ursa„Ma jor . html">Ursa Major</aX/li> 
Ursa„Mi nor. html ">Ursa Minor</aX/li> 
Vega.html ">Vega</aX/l i > 



FIGURE 2-1 



A static HTML example 
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Pegasus 
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Taunjs 
Ursa Mai or 
V>: • i 

Vega 
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Client-Side Technologies 

The most common additions to plain HTML are on the client side. These add-ons include formatting 
extensions, such as Cascading Style Sheets (CSS) and Dynamic HTML; client-side scripting lan- 
guages, such as JavaScript; VBScript; Java applets; and Flash. Support for all these technologies is (or 
is not, as the case may be) built into the web browser. They perform the tasks described in Table 2-1, 



with some 


overlap. 




TABLE 2-1 






Client-Side HTML Extensions 


Client-Side 
Technology 


Main Use 


Example Effects 


Cascading Style 
Sheets, Dynamic 
HTML 


Formatting pages: controlling size, 
color, placement, layout, timing of 
elements 


Overlapping, different colored/sized 
fonts 

Layers, exact positioning 


Client-side 
scripting 
(JavaScript, 
VBScript) 


Event handling: controlling 
consequences of defined events 


Link that changes color on mouseover 
Mortgage calculator 


Java applets 


Delivering small standalone 
applications 


Moving logo 
Crossword puzzle 


Flash animations 


Animation 


Short cartoon film 



The page shown in Figure 2-2 is based on the same content as that in Figure 2-1. As you can see 
from the following source code, however, this example adds a bit of styling with basic inline CSS. 

<!D0CTYPE HTML PUBLIC " -/ /W3C//DTD HTML 4.01//EN" "http://www.w3.org/ 

TR/html4/strict.dtd"> 

<html > 

<head> 

<STYLE TYPE="text/css"> 

BODY, P {color: black; font-family: verdana; font-size: 10 pt) 
HI {margin-top: 10; color: black; font-family: arial; font-size: 12 pt} 
H2 { ma rgi n -bottom : -10; color: black; font-family: verdana; font-size: 
18 pt) 

A : 1 ink, A:visited {color: #000080; text-decoration: none) 
</STYLE> 

<title>Selected Constellations</title> 

</head> 

<body> 

<hl>Constellations</hl> 
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<ul> 



<1 


><a 


href = 


'Aqui 1 a . html ">Aqui 1 a</a></l i > 


<1 


><a 


href = 


'Bootes . html ">Bootes</aX/l i> 


<1 


><a 


href = 


Cassiopeia. html ">Cassi ope ia</a></li> 


<1 


><a 


href = 


Cygnus . html ">Cy gnus </aX/l i > 


<1 


><a 


href = 


Deneb.html ">Deneb</aX/l i > 


<1 


><a 


href = 


Draco.html ">Draco</aX/l i> 


<1 


><a 


h ref = 


'Gemi ni . html ">Gemi ni </a></l i > 


<1 


><a 


h ref = 


'Leo. html ">Leo</aX/l i> 


<1 


><a 


h ref = 


'Libra.html ">Li bra</aX/l i> 


<1 


><a 


href = 


Lynx . html " > Ly nx</a></l i > 


<1 


><a 


href = 


Or i on. html ">0rion</aX/l i> 


<1 


><a 


href = 


Pegasus, html ">Pegasus</aX/l i> 


<1 


><a 


href = 


Perseus.html">Perseus</aX/li> 


<1 


><a 


href = 


' Pi sees . html "> Pi sees </a></l i > 


<1 


><a 


href = 


'Taurus, html ">Taurus</aX/li> 


<1 


><a 


href = 


'Ursa_Ma j or . html">Ursa Major</aX/li> 


<1 


><a 


href = 


'Ursa_Mi nor . html">Ursa Minor</aX/li> 


<1 


><a 


href = 


Vega.html ">Vega</aX/l i > 



</ul > 
</body> 
</html > 



FIGURE 2-2 



An example of HTML plus CSS. 
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Unfortunately, the best thing about client-side technologies is also the worst thing about them: They 
depend entirely on the browser. Wide variations exist in the capabilities of each browser and even 
among versions of the same brand of browser. Individuals can also choose to configure their own 
browsers in awkward ways: Some people disable JavaScript for security reasons, for example, which 
makes it impossible for them to view sites that use JavaScript incorrectly or with little care. 

The savvy web developer should also consider the implications of device-based browsing, universal 
accessibility, and a global audience. The stubborn unwillingness of the public to upgrade is the bane 
of client-side developers, causing them to frequently suffer screaming nightmares and/or existen- 
tial meltdowns in the dark, vulnerable hours before dawn. The bottom-line irony is that, even after 
almost 15 years of explosive web progress, the only thing that a developer can absolutely, positively 
know that the client is going to see is plain text-based HTML (or, rather, the subset of HTML that's 
widely supported and has stood the tests of time and usefulness). 



Server-Side Scripting 

Client-side scripting is the glamorous, eye-catching part of web development. In contrast, server-side 
scripting is invisible to the user. Pity the poor server-side scripters, toiling away in utter obscurity, 
trapped in the no-man's land between the web server and the database while their arty brethren bra- 
zenly flash their wares before the public gaze. 

Server-side web scripting is mostly about connecting web sites to backend servers, processing data 
and controlling the behavior of higher layers such as HTML and CSS. This enables the following 
types of two-way communication: 

■ Server to client: Web pages can be assembled from backend-server output. 

■ Client to server: Customer-entered information can be acted upon. 

Common examples of client-to-server interaction are online forms with some drop-down lists (usu- 
ally the ones that require you to click a button) that the script assembles dynamically on the server. 

Server-side scripting products consist of two main parts: the scripting language and the scripting 
engine (which may or may not be built into the web server). The engine parses and interprets pages 
written in the language. 

The following code shows a simple example of server-side scripting — a page assembled on the fly 
from a database. We include database calls (which we don't get around to explaining until Part II of 
this book) and leave out some of the included files, because we intend this example to show the final 
product of PHP rather than serve as a piece of working code. 

The following PHP code shows the source on the server: 
<?php 

require_once( 'db-config.inc. ' ); 
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$dbh = mysql_connect(DB_HOST,DB_USER,DB_PASSWORD) or dieC'Unable to 
connect to database."); 

mysql _sel ect_db ( ' webdb ' ) or die("Cannot access database."); 
$query = "SELECT pagetitle FROM sitepages 

WHERE site = 'braingia.org' 

AND page_i d = ' 1 ' " ; 
$qresult = mysql_query($query) or die(" Unable to query database."); 
$title = mysql _fetch_a rray ( $qresul t ) ; 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/ 

TR/html4/strict.dtd"> 

<html > 

<head> 

<STYLE TYPE="text/css"> 

BODY, P {color: black; font-family: verdana; font-size: 10 pt) 
HI {margin-top: 10; color: black; font-family: arial; font-size: 12 pt) 
H2 { ma rgi n -bottom : -10; color: black; font-family: verdana; font-size: 
18 ptl 

A : 1 ink, A:visited {color: #000080; text-decoration: none) 
</STYLE> 

<title><?php echo $title[0] ?></title> 

</head> 

<body> 

<hl>$title[0]</hl> 

<ul > 

<?php 

SlinksQuery = "SELECT descri pti on , href FROM sitepagedata 

WHERE site = 'braingia.org' 

AND pagetitle = ' {Stitle) "' ; 
Slinks Re suit = my sql_query (SlinksQuery) or die(" Unable to query 
database . " ) ; 

while ($row = mysql_f etch_ar ray ( $1 i n ks Resul t ) ) { 

print "<li><a href =\ " { $row[ 1 ] \ " >$ row[0] </a></l i >\n " ; 

) 

?> 

</ul > 
</body> 
</html > 

This particular page isn't significantly more impressive to look at than the version shown in 
Figure 2-2. 

Compare the version with the PHP code to the HTML versions shown earlier in the chapter. 
The source code that uses PHP is shorter because it retrieves the information from a database. 
Nevertheless, this server-side code is never viewable by end users. The version that they see is 
exactly the same as the HTML shown earlier. The only evidence that it's a PHP file is the filename 
extension, . php. All the heavy lifting happens before the code gets shoved down the pipe to the 
client. After emerging from the web server, the code appears on the other end as normal HTML 
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and JavaScript, which also means that you can't tell which server-side scripting language was used 
unless something in the header or URL gives it away (which usually is the case, as the page you are 
requesting often ends with . j sp or . php). These scripts, incidentally, were written in PHP using the 
MySQL database as backend; you can learn all about these techniques in Part II of this book. 



Server-Side or Client-Side? 

There are client-side methods and server-side methods to accomplish many tasks. When sending e-mail, 
for example, the client-side way is to open up the mail client software with a preaddressed blank e-mail 
message after the user clicks a MAILTO link. The server-side method is to make the user fill out a form, and 
the contents are formatted as an e-mail that is sent via a Simple Mail Transfer Protocol (SMTP) server (which 
very well could be the same machine that the server-side script is executing on). You can also choose between 
client methods and server methods of browser-sniffing, form validation, drop-down lists, and arithmetic cal- 
culation. Sometimes you see subtle but meaningful differences in functionality (server-side drop-downs can 
be assembled dynamically; client-side cannot) but not always. 

How to choose? Know your audience. Server-side methods are generally a bit slower at runtime because of 
the extra transits they must make, but they don't assume anything about your visitor's browser capabilities and 
take less developer time to maintain. 



What Is Server-Side Scripting Good For? 

Server-side scripting languages such as PHP perfectly serve most of the truly useful aspects of the 
web, such as the items in this list: 

■ Content sites (both production and display) 

■ Community features (forums, bulletin boards, and so on) 

■ E-mail (web mail, mail forwarding, and sending mail from a web application) 

■ Customer-support and technical-support systems 

■ Advertising networks 

■ Web-delivered business applications 

■ Directories and membership rolls 

■ Surveys, polls, and tests 

■ Filling out and submitting forms online 

■ Personalization technologies 

■ Groupware 
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■ Catalog, brochure, and informational sites 

■ Games (for example, chess) with lots of logic but simple/static graphics 

■ Any other application that needs to connect a backend server (database, Lightweight 
Directory Access Protocol [LDAP], and so on) to a web server 

PHP can handle all these essential tasks — and then some. 

But enough rhetoric! Now that you have a grasp of the differences between client-side and server- 
side technologies, you can get on to the practical stuff. In Chapter 3, we show you how to get, install, 
and configure PHP for yourself (or find someone to do it for you). 



Summary 

To understand what PHP (or any server-side scripting technology) can do for you, having a firm 
grasp on the division of labor between client and server is crucial. In this chapter, we worked 
through examples of plain, static HTML; HTML with client-side additions such as JavaScript and 
Cascading Style Sheets; and PHP-generated web pages as viewed from both the server and the client. 

Client-side scripting can be visually attractive and quickly responsive to user inputs, but anything 
beyond the most basic HTML is subject to browser variation. Static client-side scripts also require 
more developer time to maintain and update, because pages cannot be dynamically generated from a 
constantly changing datastore. Server-side programming and scripting languages, such as PHP, can 
connect databases and other servers to web pages. 
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In this chapter, we'll give detailed directions for installing PHP and fin- 
ish with a few tips on finding the right development tool. By the end of 
the chapter, you should be ready to write your first script. 



Installing PHP 

This section looks at the installation of PHP onto a computer. If you're going 
to be using a hosting provider that provides PHP or if you have a friendly 
sysadmin who has installed PHP for you, then this section will be of limited 
usefulness. PHP runs on various platforms, including Linux, various Unix 
flavors, Microsoft Windows, and Mac OS X. Linux is the most popular plat- 
form for PHP, and when combined with the Apache web server, and MySQL 
forms the acronym LAMP (although the "P" can also be Perl or Python). 

If you plan to install PHP on Windows, you'll also need: 

■ A working PHP-supported web server. Under previous versions 
of PHP, IIS/PWS was the easiest choice because a module version 
of PHP was available for it; but PHP now has added a much wider 
selection of modules for Windows. These days, Apache works very 
well with Windows, so we'll be focusing on PHP with Apache on 
Windows. 

■ The PHP Windows binary distribution (download it at www . php 

. net/downl oads . php) 

■ A utility to unzip files (search http://download.cnet. com for 
PC file compression utilities), if your version of Windows doesn't 
include such a utility. 



IN THIS CHAPTER 



Installing PHP 
Coding in PHP 
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If you plan to install PHP on Linux, you may be able to take advantage of your distribution's PHP 
package. Most Linux distributions, including Red Hat, Debian, SuSE, and Ubuntu, include PHP as 
an available package, and, where possible, you should use the distribution's official PHP package. 

Lhere are certain instances where you need to compile PHP from source, in order to take advantage 
of a bleeding-edge feature, for example, but these are the rare exceptions. It is much easier and much 
more stable to use the distribution's PHP package. 

Additionally, you need a web server that supports PHP. Most of the time this will be the Apache web 
server, but others work well with PHP. For this book, we'll be concentrating on Apache as the web 
server of choice. Therefore, you'll need to install Apache from your distribution, as well. 



Installation procedures 

Because of PHP's strong commitment to cross-platform operability, there are far too many specific 
installation methods to fully list here. We have tried to cover what we believe to be the most popular 
platforms for PHP, but trying to write the installation instructions for every possible operating sys- 
tem and web server would have resulted in a prohibitively long chapter. 

Furthermore, while PHP installation procedures under Unix have been stable for years, Windows 
installs have gone through quite a bit of flux since PHP4 was first released. Part of this is the result 
of actions on the part of the PHP team; part of this is because of changes in the Windows product 
line. PHP also runs on Macintosh OS X, and that installation has only fairly recently stabilized. 

In response to such rapid change, we can only caution you that for the freshest information on 
installation you should visit the PHP web site (www .php.net/docs .php) on each download. Even 
if you've installed PHP a gazillion times before, there might be something new and different on the 
gazillion-and-first occasion. 

For those who have already successfully built an earlier version of PHP, the procedure is exactly the 
same — only it takes a lot longer than before. 

' : - 3 1 r)*'.'t' Your Red Hat, Mandrake, or SuSE Linux installation may have come with RPM versions 

of Apache and PHP, or your Debian Linux may have come with a deb package. You must 
remove these packages before compiling your new PHP! In addition, you may have RPM or apt ver- 
sions of third-party servers, such as MySQL or PostgreSQL, which are generally installed differently 
from their source counterparts. If you encounter problems, look in the documentation for installation 
locations, or uninstall the packages and reinstall from scratch. Nevertheless, I strongly recommend 
using the distribution's version of the package unless you have specific reasons for doing otherwise. 
If you choose to compile your own versions of PHP and Apache from source then you must maintain 
them by hand. This means that each and every time a security update is released for either, or for a 
library touching either, PHP or Apache, you need to recompile the server in order to remain up to date. 
Otherwise, just use the distribution's package. They'll maintain the security updates, leaving you to 
concentrate on things like programming PHP! 
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The following procedures give an overview of PHP installation on CentOS and Debian. As of this 
writing, the only version of PHP officially available with these distributions is PHP5. We expect 
these instructions to be valid when PHP6 becomes available with the distributions. 



Installing PHP on CentOS 

The YellowDog Update Manager (yum) is available with CentOS and is somewhat like the dpkg and 
apt toolset from Debian. Therefore, installation of PHP and Apache on CentOS is rather trivial. From 
the command-line as root, type: 

yum install php 

Doing so will cause the yum system to examine the system, gather any prerequisites, and inform 
you of the installation's progress. Our example system is a fresh CentOS 5.1 install with a minimal 
package set. Therefore, yum needs to install several prerequisites, and a summary is shown. 

After downloading the prerequisites (if necessary), yum will go about its business and install PHP. 
Part of the install includes Apache, known as "httpd" in CentOS terminology. Apache 2 is installed 
as part of the installation of PHP. 

Apache isn't started by default. To start it, run: 

/etc/i ni t . d/httpd start 

While Apache is installed, it is firewalled by default in CentOS, meaning that you can't get to the 
web server through its default protocol and port, tcp/80. To alleviate this problem, edit /etc/ 
sysconf i g/i ptabl es and add this line, second from the bottom: 

-A RH-Fi rewal 1 -1-INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j 
ACCEPT 



The final file looks like this: 



# Firewall configuration written by 

# Manual customization of this file 
*filter 

INPUT ACCEPT [0:0] 
FORWARD ACCEPT [0:0] 
OUTPUT ACCEPT [0:0] 
RH-Fi rewal 1 -1-INPUT - [0:0] 
INPUT -j 
FORWARD 



-A 
-A 
-A 
-A 
-A 
-A 
-A 
-A 
-A 



RH-Fi rewal 1 -1-INPUT 
-j RH-Fi rewal 1 -1-INPUT 



sy st em -config-security level 
is not recommended. 



RH-F 
RH-F 



RH- 
RH- 
RH- 
RH- 



rewal 1 -1-INPUT 
rewal 1 -1-INPUT 
rewal 1 -1-INPUT 
rewal 1 -1-INPUT 
rewal 1 -1-INPUT 
rewal 1 -1-INPUT 



- 1 



lo -j ACCEPT 

i cmp --i cmp-type 



RH-Fi rewal 1 -1-INPUT -p 



50 - 

51 - 
udp 
udp 
tcp 



any -j ACCEPT 



j ACCEPT 
j ACCEPT 
--dport 5353 
-m udp --dport 
-m tcp --dport 



d 224. 

631 - 
631 - 



0.251 - 

ACCEPT 

ACCEPT 



j ACCEPT 
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-A RH-Firewall 


-1- 


INPUT 


-m 


state 


--state ESTABLISHED 


.RELATED -j ACCEPT 


-A RH-Firewall 


-1- 


INPUT 


-m 


state 


--state NEW -m tcp 


-p tcp --dport 22 -j 


ACCEPT 














-A RH-Firewall 


-1- 


INPUT 


-m 


state 


-state NEW -m tcp 


-p tcp -dport 80 -j 


ACCEPT 














-A RH-Firewall 


-1- 


INPUT 


-J 


REJECT 


--reject-wi th icmp 


-host-prohi bi ted 



COMMIT 

Restart the iptables firewall by running: 

/etc/i ni t . d/i ptabl es restart 

With that, you'll be able to access your web server with PHP enabled by visiting http : / / your 

. i p . address/ in the browser. For example, my CentOS computer is 192.168.1.155 and so pointing 

to that in the web browser looks like this: 

http://192.168. 1.155 

You may also want to install MySQL through the yum installer and the PHP/MySQL libraries: 

yum install mysql php-mysql mysql-server mysql -devel 

Installing PHP on Debian 

Installation of PHP (or really anything) on Debian is probably the easiest and most manageable of all 
Linux distributions with which I've worked (and that's more than a few). Installation of the Debian 
PHP package is done through the apt-get utility: 

apt-get install 1 i bapache2-mod-php5 



This will install not only the PHP module for Apache 2 but also Apache 2 itself, if the web server 
software hasn't already been installed. 

Once installed, the web server is ready to use. You'll find the default location for PHP files at / v a r / 
www/ apache2-default/, though that location may change in future releases of Debian. 

Installing PHP from source 

In the following directions, you will type the code fragments into each shell prompt, substituting the 
version of software shown in the examples for the version that you're compiling. 

You'll need a C compiler, with GCC being a good choice. On Debian you can install gcc by typing 
apt-get install gcc, whereas on CentOS you can install GCC by typing yum install gcc. 

You'll also need ICU (International Components for Unicode) for Unicode support. On CentOS, this 
is installed with yum install icu 1 i bi cu- devel . 



This example shows the installation of the PHP5 module on Debian because the PHP6 
module was not yet available at the time of this writing. 
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Finally, you'll also need development libraries for libxml, which can be installed on CentOS through 
the libxml2-devel package, yum install 1 i bxml 2-devel . 

If you'll be using MySQL you can install it and the libraries from the command line with the yum 
installer: 

yum install mysql mysql-server mysql-devel 



"J" J JJ ^' [ Remember to log in as the root user first if you are installing in a root-owned directory. 
- ■' Remember to stop and uninstall your previous Apache server if you had one. 

To start your build, just follow these steps: 

1 . If you haven't already done so, unzip and untar your Apache source distribution. Unless 
you have a reason to do otherwise, / usr/local is the standard place to do so. 

tar -zxvf httpd-2 . 2 . x . ta n . gz 

2 . Build the Apache server: If you are installing somewhere other than / usr/local, this is 
the time to say so with the --prefix flag as follows. If you are installing in / usr/local, 
don't worry that the apache directory mentioned in a moment doesn't exist — it will by 
the end of the build process. The - -enable-so flag will allow Apache to load PHP sup- 
port (and many other things) as a module called a Shared Object. This is how you'll build 
your PHP module later on. After the configuration finishes, the next two commands will 
build the binaries and then drop everything in the appropriate place according to the target 
of the --prefix flag. 

cd apache_2.2.x 

./configure --prefix=/usr/local/apache --enable-so 
ma ke 

make install 

3. Unzip and untar your PHP source distribution. Unless you have a reason to do otherwise, 
/usr/local is the standard place to do so. 

tar -zxvf php-6 . x . ta r . gz 
cd php-6. x 

4. Configure your PHP build. (Configuring PHP is a topic so large and important that it 
would not fit into this chapter, so please flip over to Chapter 29 for more information.) 
The most common options are the ones to build as an Apache module, which you almost 
certainly want, and to do so with specific database support. The example build here is an 
Apache module with MySQL support, built using apxs. 

./configure 

--with-apxs2=/usr/local/apache/bin/apxs 
--with-mysql 

5. Make and install the PHP module, 
ma ke 

make install 
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6. Install the php . i ni file. Edit this file to get configuration directives; see the options listed 
in Chapter 29. At this point, we highly recommend that new users set error reporting to 
E_ALL on their development machines. 

cd . . / . . /php-6 . x 

cp php.ini-dist /usr/1 ocal /I ib/php. ini 

7. Tell your Apache server what extension(s) you want to identify PHP files (.php is the stan- 
dard, but you can use .html, . phtml , or whatever you want). Go to your HTTP configura- 
tion files (/usr/local / apache/conf or whatever your path is), and open httpd.conf 
with a text editor. Add at least one PHP extension directive, as shown in the first line of 
code that follows. In the second line, we've also added a second handler to have all HTML 
files parsed as PHP (which does impose a small performance hit and should not be done if 
your architecture uses the .html file extension strictly for HTML-only files). This would 
also be a good time for you to ensure that Apache knows what domain alias or IP address 
to listen for. (If you have no idea what this means, search httpd.conf for the word 
ServerName, add the word 1 ocal host right after it, and use that as your domain name 
until you get a better one.) 

AddType appl i cati on/x-httpd-php .php 
AddType appl i cati on/x-httpd-php .html 

8. Restart your server. Every time you change your HTTP configuration or p h p . i n i files, you 
must stop and start your server again. An HUP signal will not suffice. 

c d ../bin 

./apachectl start 

9. Set the document root directory permissions to world-executable. The actual PHP files in 
the directory need only be world-readable (644). If necessary, replace /home/httpd with 
your document root in the code that follows. 

chmod 755 /home/httpd/html /php 

10. Open a text editor. Type: <?php phpi nf o ( ) ; ?>. Save this file in your web server's docu- 
ment root as i nf o . php. Start any web browser and browse the file — you must always 
use an HTTP request (http : / /www .example. com /info. php or http://localhost/ 
info. php or http://127.0.0.1/info.php) rather than a filename (/home/httpd/ 
i nf o . php) for the file to be parsed correctly. You should see a long table of information 
about your new PHP6 installation. Congratulations! 



CROSS-REF 



Many Apache production servers do not use a php . i ni file; it can be undesirable to 
have two different configuration files in two different locations. You can replicate many 
of the configuration directives of php . i n i in your Apache httpd . conf file. At a minimum, you prob- 
ably want to set the include path and error-reporting levels, because the default settings for these are 
often unsatisfactory. See Chapter 29 for more details. 
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Microsoft Windows and Apache 

As with the LAMP (Linux/Apache/MySQL/Perl/PHP/Python) stack, the last several years has seen 
a rise in the WAMP stack (Windows/Apache/MySQL/Perl/PHP/Python). If Microsoft Windows is 
your OS of choice, then you'll have no problem running any of these popular packages, just like 
your Linux brethren. Apache, PHP, and MySQL all offer installers and source code for Windows. 
This section examines installation on Microsoft Windows Server 2008, Windows Server 2003, and 
Windows Vista. 



NOTE 



Microsoft Windows XP is still quite popular on the desktop, and installation of these 
components on Windows XP is roughly the same as the installation on Windows 



Server 2003. 

To install Apache with PHP on Microsoft Windows Vista and Windows Server 2003 and 2008: 

1. Download Apache server from http://httpd. apache, org/download. eg i. You want 
the current stable release version with the no_src.msi extension (You can try the . e x e 
version if there is one, but it doesn't work on all systems and isn't any easier). Once down- 
loaded, double-click the installer file to install. The installer will run through a wizard. For 
our intents and purposes in this book, you can accept the defaults. As you gain experience 
with the Apache server, you may find that you want to adjust and tweak the configuration, 
but for now, the defaults are fine. 

You may need to stop Internet Information Server (IIS) in Windows prior to starting 
Apache, since both will attempt to listen on TCP port 80. You may also need to allow 
Apache through the firewall in Windows. In Vista, this is accomplished through the 
Security Center Control Panel in Windows Vista. Specifically, by using the "Allow a pro- 
gram through Windows Firewall" option, clicking on Add Port, and then configuring TCP 
port 80 within the Add a Port dialog. In Windows Server 2008, the Windows Firewall with 
Advanced Security applet is found in Administrative Tools. Within the Windows Firewall 
with Advanced Security applet, clicking on Inbound Rules on the left and then New Rule 
on the right will result in a New Inbound Rule Wizard. Follow the wizard to add a TCP 
port of 80 inbound. 

2. Next, download PHP from www .php.net/downloads.php. If there's an installer avail- 
able, get it. Otherwise get the zip file version. If you download the installer, then you can 
merely follow through the Installation Wizard. Otherwise, for the zip version of PHP, 
extract the PHP binary archive using your unzip utility placing it in C : \ PH P. 

3. Copy some . dl 1 files from your PHP directory to your system directory (usually C : \ 

Wi ndows\System32). You need php6ts . dl 1 for every case. You will also probably need 
to copy the file corresponding to your web server module — C:\PHP\php6apache 2_2 . 
d 1 1 — to your Apache modules directory. It's possible that you will also need other files 
from the d 1 1 s subfolder — but start with the two mentioned previously and add more 
if you need them. For instance, it's quite common to need to copy 1 i bmysql . dl 1 from 
C:\PHP to C: \ Windows\System32 as well, so you might as well copy it there now. In 
Windows Vista, I've found that the easiest way to do this is to right-click on the command 
prompt, select Run as Administrator, and then copy the files using the copy command, as 
in copy c:\php\php6ts.dll c:\windows\system32\. 
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4. Rename either php.ini-distorphp.ini - recommended (preferably the latter) as php . 
i n i within your C:\PHP directory. Open this file in a text editor (for example, Notepad). 
Edit this file to get configuration directives; see the options listed in Chapter 29. At this 
point, we highly recommend that new users set error reporting to E_ALL on their devel- 
opment machines. Note that it's not strictly necessary to edit the file at this time, but you 
should be familiar with its contents nonetheless. 

5. Go to your HTTP configuration files (C:\Program FilesXApache Software 
Foundation\Apache2.2\confor whatever your path is), and open httpd.conf with a 
text editor. Add the PHP module load directive as shown in the first line of the following 
code and add the handler for .php and . phtml files, too: 

LoadModule php6_module modul es /php6apache2_2 . dl 1 
AddType appl i cati on/x-httpd-php .php .phtml 

6. Stop and restart the WWW service. Go to the Start menu O All Programs O Apache 
HTTP Server 2.2 O Control Apache HTTP Server O Stop/Start; or Restart, or even run 
Apache from the MS-DOS prompt. 

7. Open a text editor (for example, Notepad). Type: <?php phpi nfo( ) ; ?>. Save this 
file in your web server's document root (C:\Program Fi 1 es\ Apache Sof twa re 
Foundation\Apache2.2\htdocsby default) as i nf o . php. Start any web browser and 
request the file: http : 1 1~\ ocal host / info. php or http : / /127 . 0 . 0 . 1/i nf o. php). You 
should see a long table of information about your new PHP6 installation. Congratulations! 
If things didn't go as planned, check the error log for Apache, usually located at C : \ 
Program FilesXApache Software Foundation\Apache\logs\error.log. 



p ■ > j £j ~" >j. rV If you follow these directions and don't get the results you expected, don't panic! Check 
w ■ out Chapter 10 for common gotchas and quirks. If that doesn't help, check out the com- 

ments on the relevant pages in the PHP online manual — users leave specific tips for specific setups 
they've had problems with. 

Other web servers 

PHP has been successfully built and run with many other web servers, such as Netscape Enterprise 
Server, Xitami, Zeus, and thttpd. Module support for AOLServer, NSAPI, and fhttpd is available. See 
the relevant pages on the PHP online manual's installation section. 



Development tools 

When it comes to development tools, PHP used to fall between the cracks — between tools origi- 
nally designed for other programming languages and those mainly used to create pretty HTML. It's 
certainly possible to write a complex 2000-line program that touches several other services and file- 
systems and outputs the string 1 to the browser on completion. On the other hand, there are many 
people whose main use of PHP is to slap common headers and footers on what amounts to a bunch 
of static HTML pages. With such a diversity of usages, it's perhaps not so amazing that the perfect 
PHP development environment — user-friendly enough for the designers, but light and powerful 
enough for the geeks — has been elusive. 
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Those coming to PHP from a strictly client-side perspective probably have the hardest adjustment 
to make. There's no such thing as a plush development environment with wizards and drag- 
and-drop icons and built-in graphics manipulation. If that sort of thing is important to you, you 
can use a WYSIWYG editor to format the page and then add PHP functionality later using a text 
editor. The downside of this strategy is, of course, that machine-written code is often not very 
human-readable — but one must suffer to be pretty. 

The last year and a half, however, has seen substantial change in the market. Plenty of editors for 
both Windows and Linux now offer at least syntax highlighting for PHP. Several of these can map 
drive locations to server names, so you can debug in place. 



Old-school programmers will have less of a learning curve, since they can treat PHP like any other 
server-side programming language that may or may not happen to output HTML to a browser. Most 
PHP users in this category seem to prefer simple text editors. Generally, these products will afford 
you a modest amount of help, such as syntax highlighting, brace matching, or tag closing — most of 
which is about helping you avoid stupid mistakes rather than actually writing the script for you. 

My favorite is good old Vi, or Vi-Enhanced, Vim, although many people have problems using Vi. 
An excellent GUI tool is Eclipse. I've been using Eclipse for quite some time and feel comfortable 
recommending it for development in PHP, JavaScript, HTML, and just about any other language. 
Get Eclipse from www .eel ipse.org. 



The remainder of this chapter looks at some basics of PHP, focusing on getting you up to speed for 
the rest of the book! 



PHP is already perfectly at home with HTML — in fact, it is generally embedded within HTML. As 
you'll see in later chapters, PHP rides piggyback on some of the cleverer parts of the HTML stan- 
dard, such as forms and cookies, to do all kinds of useful things. 

Anything compatible with HTML on the client side is also compatible with PHP. PHP could not care 
less about chunks of JavaScript, calls to music and animation, applets, or anything else on the client 
side. PHP will simply ignore those parts, and the web server will happily pass them on to the client. 

It should be clear that you can use any method of developing web pages and simply add PHP to that 
method. If you're comfortable having teams work on each page using huge multimedia graphics 
suites, you can keep doing that. The general point is that you don't need to change tools or workflow 
order, just do what you've been doing and add the server-side functionality at the end. 




Be particularly careful with using Microsoft FrontPage or Adobe Dreamweaver as a PHP 
editor, as they both leave something to be desired for PHP development. . 



What's to Come? 



Your HTML Is Already PHP-Compliant! 
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Escaping from HTML 



By now you're probably wondering: How does the PHP parser recognize PHP code inside your 
HTML document? The answer is that you tell the program when to spring into action by using 
special PHP tags at the beginning and end of each PHP section. This process is called escaping from 
HTML or escaping into PHP. 



- ; 

■Hi«AIw^fciM mon use of the term escape in PHP: putting a backslash in front of certain special charac- 
ters (such as tab and newline) within double-quoted strings. Escaping strings is explained in Chapter 7. 

Everything within these tags is understood by the PHP parser to be PHP code. Everything outside of 
these tags does not concern the server and will simply be passed along and left for the client to sort 
out whether it's HTML or JavaScript or something else. 

There are several styles of PHP, but it's best to stick with the tried-and-true tags that will always 
work no matter which version of PHP you're using: 

Canonical PHP tags 

The most universally effective PHP tag style is: 
<?php ?> 

If you use this style, you can be positive that your tags will always be correctly interpreted. Unless 
you have a very, very strong reason to prefer another style, use this one. Some or all of the other 
styles of PHP tag may be phased out in the future — only this one is certain to be safe. 



Not to confuse you, but escape in this sense should not be confused with another com- 



Hello World 

Now you're ready to write your first PHP program. Open a new file in your preferred editor. Type: 

<HTML> 
<HEAD> 

<TITLE>My first PHP program</TITLE> 
</HEAD> 



<B0DY> 
<?php 

print ("Hello. World<BR />\n"); 

phpi nf o ( ) ; 

?> 

</B0DY> 
</HTML> 



In most browsers, nothing but the PHP section is strictly necessary; however, it's a good idea to get 
in the habit of always using a well-formed HTML structure in which to embed your PHP. 
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If you don't see something pretty close to the output shown in Figure 3-1, you have a problem — 
most likely some kind of installation or configuration glitch. Review Chapter 2 and make doubly 
sure that your installation succeeded. 



FIGURE 3-1 



Your first PHP script 
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Refer back to Chapter 2 for installation instructions and forward to Chapter 29 for configuration 
options. Chapter 10 diagnoses some common early problems and gives debugging hints. 
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Jumping in and out of PHP mode 

At any given moment in a PHP script, you are either in PHP mode or you're out of it in HTML. 
There's no middle ground. Anything within the PHP tags is PHP; everything outside is plain HTML, 
as far as the server is concerned. 

You can escape into PHP mode with giddy abandon, as often and as briefly or lengthily as necessary. 
For example: 

<?php lid = 1; ?> 

<F0RM METH0D="P0ST" ACTI0N=" regi strati on . php" "> 
<P> Fi rst name: 

<INPUT TYPE="TEXT" N AM E= " f i rstname" SIZE="20"> 
<P>Last name: 

<INPUT TYPE="TEXT" N AM E= " 1 astname" SIZE="20"> 
<P>Rank: 

<INPUT TYPE="TEXT" NAME="rank" SIZE="10"> 

< INPUT TYPE="HIDDEN" NAME="serial number" VALUE="<?php 

echo $id; ?>"> 

<INPUT TY PE=" submi t " SUBM IT" VALUE=" I NPUT" " > 

</F0RM> 

Notice that things that happened in the first PHP mode instance — in this case, a variable being 
assigned — are still valid in the second. In Chapter 4, you'll learn more about what happens to vari- 
ables when you skip in and out of PHP mode. In Chapter 32, you'll also learn about different styles 
of using PHP mode. 

Including files 

Another way you can add PHP to your HTML is by putting it in a separate file and calling it by using 
PHP's 1 ncl ude functions. There are four i ncl ude functions: 

■ include( '/filepath/filename' ) 

■ requi re ( '/filepath/filename' ) 

■ i ncl ude_once( '/filepath/filename') 

■ requi re_once( '/filepath/filename' ) 



In previous versions of PHP, there were significant differences in functionality and speed between 
the i ncl ude functions and the requi re functions. This is no longer true; the two sets of functions 
differ only in the kind of error they throw on failure. I ncl ude ( ) and i ncl ude_once ( ) will merely 
generate a warning on failure, while requi re ( ) and requi re_once ( ) will cause a fatal error and 
termination of the script. 

As suggested by the names of the functions, include_once() and require_once() differ from 
simple i n c 1 u d e ( ) and requi r e ( ) in that they will allow a file to be included only once per PHP 
script. This is extremely helpful when you are including files that contain PHP functions, because 
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redeclaring functions results in an automatic fatal error. In larger PHP systems, it's quite common 
to include files that include other files that include other files — it can be difficult to remember 
whether you've included a particular function before, but with i ncl ude_once( ) or requi re_ 
once ( ) you don't have to. 

How do you decide on a preferred include function? In essence, you must decide whether you 
want to force yourself to write good code on pain of fatal error or whether you want it to run regard- 
less of certain common errors on your part. The strictest alternative is r e q u i r e ( ) , which will bring 
everything grinding to a halt if your code isn't perfect; the least strict is i ncl ude_once ( ) , which 
will good-naturedly hide the consequences of some of your bad coding habits. 

The most common use of PHP's i ncl ude capability is to add common headers and footers to all the 
web pages on a site. For example, a simple header file (cleverly named header. php) might look 
like this: 

<HTML> 
<HEAD> 

<TITLE>A site ti tl e</TITLE> 
</HEAD> 

<B0DY> 

Similarly, a footer file called footer, php might consist of: 

<P>Copyright 1995 - 2002</P> 

</B0DY> 

</HTML> 

They are called from a PHP page this way: 
<?php 

requi re_once( $_SERVER[ ' D0CUMENT_R00T ' ].' /header . php ') ; 
?> 

<P>This is some body text for this particular page.</P> 
<?php 

requi re_once($_SERVER[ ' D0CUMENT_R00T ' ] . 1 /footer .php' ) ; 
?> 



Obviously, this single move greatly enhances the maintainability and scalability of an entire site. 
Now, if you want a different look and feel or if you need to update the copyright notice, you can alter 
one file instead of identical lines in dozens of HTML pages. 

p77/~" F When including files, remember to set the i ncl ude„path directive correctly in your 

- php . i n i file. Remember that you can include files from above or entirely outside your 
web tree by proper use of this directive. See Chapter 29 for more information. 

As you can see from the preceding example, PHP's i ncl ude functions simply pass along the con- 
tents of the included file as text. Many people think that because an i ncl ude function occurs inside 
PHP mode, the included file will also be in PHP mode. This is not true! Actually, the server escapes 
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back into HTML mode at the beginning of each included file and silently returns to PHP mode at the 
end, just in time to catch the semicolon. 

As always, you need to say when you intend something to be PHP by using PHP opening and closing 
tags. Any part of an included file that needs to be executed as PHP should be enclosed in valid PHP 
tags. If the entire file is PHP (very common in files of functions), the entire file must be enclosed 
within PHP tags. 

Take the following file, database. php: 

$db = mysql_connect ( ' 1 ocal host ' , 'db_user', ' db_password ' ) ; 
mysql_select_db( ' my_d a t a b a s e ' ) ; 



CAUTION 



We can't emphasize this enough: If you're having problems including PHP files, par- 
ticularly if you're seeing output you don't expect or not seeing output you do expect, be 
ABSOLUTELY POSITIVE that you've put PHP tags at the beginning and end of the included file. 



If you were to foolishly include this file from a PHP script, your database variables would be visible 
to the world in plain text — because you neglected to use PHP tags, the parser assumes that this 
block of code is HTML. A correct version of the database. php file would look like this: 



<?php 

$db = mysql _connect ( ' 1 ocal host ' , 
mysql_select_db( ' my_d a t a b a s e ' ) ; 
?> 



'db_user', ' db_password ' ) 



r r* , '■ 1 - jvj'- ' For all PHP files included from other files, you must ensure that there are no empty new 
^Smm^m&mm^R lines at the end of the file. Remember, anything outside a PHP block is considered HTML, 
even a blank line. Blank lines, or even blank spaces outside a closing PHP tag, will be interpreted as 
output. If you include the file in a situation where you cannot have output — say before using HTTP 
headers — your script will fail with a big error message about the output stream having already been 
started in your included file. See Chapter 10 for an example. 



Summary 

This chapter gets you up to speed with PHP, beginning with installation instructions for the several 
common platforms. Finally, some coding was shown in this chapter through the venerable "Hello 
World" example, illustrating not only that your PHP installation is working, but also that you can 
code in PHP! 
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Learning PHP Syntax 
and Variables 



In this chapter, we cover the basic syntax of PHP — the rules that all 
well-formed PHP code must follow. We explain how to use variables to 
store and retrieve information as your PHP code executes and the type 
of system that governs what kinds of values can be stored in the first place. 
Finally, we look at the simplest ways to display text that will show up in 
your user's browser window. 



PHP Is Forgiving 



The first and most important thing to say about the PHP language is that 
it tries to be as forgiving as possible. Programming languages vary quite 
a bit in terms of how stringently syntax is enforced. Pickiness can be a 
good thing because it helps make sure that the code you're writing is really 
what you mean. If you are writing a program to control a nuclear reactor 
and you forget to assign a variable, it is far better to have the program be 
rejected than to create behavior different from what you intended. PHP's 
design philosophy, however, is at the other end of the spectrum. Because 
PHP started life as a handy utility for making quick web pages, it empha- 
sizes convenience for the programmer over correctness; rather than have a 
programmer do the extra work of redundantly specifying what is meant by 
a piece of code, PHP requires the minimum and then tries its best to figure 
out what was meant. Among other things, this means that certain syntacti- 
cal features that show up in other languages, such as variable declarations 
and function prototypes, are simply not necessary. 



IN THIS CHAPTER 



Understanding the basic rules 
of PHP 
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Constants, variables, and data 
types 

Output to HTML 
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With that said, though, PHP can't read your mind; it has a minimum set of syntactical rules that 
your code must follow. Whenever you see the words parse error in your browser window instead 
of the cool web page you thought you had just written, it means that you've broken these rules to the 
point that PHP has given up on your page. 



The second most important thing to understand about PHP syntax is that it applies only within PHP. 
Because PHP is embedded in HTML documents, every part of such a document is interpreted as 
either PHP or HTML, depending on whether that section of the document is enclosed in PHP tags. 

PHP syntax is relevant only within PHP, so we assume for the rest of this chapter that PHP mode is 
in force — that is, most code fragments will be assumed to be embedded in an HTML page and sur- 
rounded with the appropriate tags. 



The third most important thing to know about PHP syntax is that, broadly speaking, it is like the 
C programming language. If you happen to be one of the lucky people who already know C, this is 
very helpful; if you are uncertain about how a statement should be written, try it first the way you 
would do it in C, and if that doesn't work, look it up in the manual. The rest of this section is for the 
other people, the ones who don't already know C. (C programmers might want to skim the headers 
of this section and also see Appendix A, which is specifically for C programmers.) 



Whites-pace is the stuff you type that is typically invisible on the screen, including spaces, tabs, 
and carriage returns (end-of-line characters). PHP's whitespace insensitivity does not mean that 
spaces and such never matter. (In fact, they are crucial for separating the words in the PHP lan- 
guage.) Instead, it means that it almost never matters how many whitespace characters you have in 
a row — one whitespace character is the same as many such characters. 

For example, each of the following PHP statements that assigns the sum of 2 + 2 to the variable 
$f our is equivalent: 

$four = 2 + 2; // single spaces 

$four <tab>=<tab>2<tab>+<tab>2 ; // spaces and tabs 

$four 

2 



HTML Is Not PHP 



PHP'i 



s Syntax Is C-Like 



PHP is whitespace insensitive 



+ 



2; 



// multiple lines 
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The fact that end-of-line characters count as whitespace is handy, because it means you never have 
to strain to make sure that a statement fits on a single line. 

PHP is sometimes case sensitive 

Having read that PHP isn't picky, you may be surprised to learn that it is sometimes case sensitive 
(that is, it cares about the distinction between lowercase and capital letters). In particular, all vari- 
ables are case sensitive. If you embed the following code in an HTML page: 

<?php 

$capital = 67; 

pri nt( "Vari abl e capital is $capi tal <BR>" ) ; 
printC'Variable CaPiTaL is $CaPiTal_<BR>" ) ; 

?> 

The output you will see is: 

Variable capital is 67 
Variable CaPiTaL is 

The different capitalization schemes make for different variables. (Surprisingly, under the default 
settings for error reporting, code like this fragment will not produce a PHP error — see the section 
"Unassigned variables," later in this chapter.) 

On the other hand, unlike in C, function names are not case sensitive, and neither are the basic lan- 
guage constructs (if, then, else, while, and the like). 

Statements are expressions terminated 
by semicolons 

A statement in PHP is any expression that is followed by a semicolon (;). If expressions correspond 
to phrases, statements correspond to entire sentences, and the semicolon is the full stop at the end. 
Any sequence of valid PHP statements that is enclosed by the PHP tags is a valid PHP program. Here 
is a typical statement in PHP, which in this case assigns a string of characters to a variable called 
$greeti ng: 

$greeting = "Welcome to PHP!"; 

The rest of this subsection is about how such statements are built from smaller components and how 
the PHP interpreter handles the evaluation of statements. (If you already feel comfortable with state- 
ments and expressions, feel free to skip ahead.) 

Expressions are combinations of tokens 

The smallest building blocks of PHP are the indivisible tokens, such as numbers (3.14159), strings 
("two"), variables ($two), constants (TRUE), and the special words that make up the syntax of PHP 
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itself (if, else, and so forth). These are separated from each other by whitespace and by other spe- 
cial characters such as parentheses and braces. 

The next most complex building block in PHP is the expression, which is any combination of tokens 
that has a value. A single number is an expression, as is a single variable. Simple expressions can 
also be combined to make more complicated expressions, usually either by putting an operator 
in between (for example, 2 + ( 2 + 2 ) ) or by using them as input to a function call (for example, 
pow( 2*3, 3*2)). Operators that take two inputs go in between their inputs, whereas functions 
take their inputs in parentheses immediately after their names, with the inputs (known as argu- 
ments) separated by commas. 

Expressions are evaluated 

Whenever the PHP interpreter encounters an expression in code, that expression is immediately 
evaluated. This means that PHP calculates values for the smallest elements of the expression and suc- 
cessively combines those values connected by operators or functions, until it has produced an entire 
value for the expression. For example, successive steps in an imaginary evaluation process might 
look like: 

$result =2*2+3*3+5; 

(=4+3*3+5) //imaginary evaluation steps 
(=4+9+5) 
(= 13 + 5) 
(= 18) 

with the result that the number 18 is stored in the variable $ res ul t. 

Precedence, associativity, and evaluation order 

There are two kinds of freedom PHP has in expression evaluation: how it groups or associates sub- 
expressions and the order in which it evaluates them. For example, in the evaluation process just 
shown, multiplications were associated more tightly than additions, which affects the end result. 

The particular ways that operators group expressions are called precedence rules — operators that 
have higher precedence win in grabbing the expressions around them. If you want, you can memo- 
rize the rules, such as the fact that * always has higher precedence than +. Or you can just use the 
following cardinal rule: When in doubt, use parentheses to group expressions. 

For example: 

$resultl =2+3*4+5; //is equal to 19 
$result2 = (2 + 3) * (4 + 5); // is equal to 45 

Operator precedence rules remove much of the ambiguity about how subexpressions are associated. 
But what about when two operators have the same precedence? Consider this expression: 

$how_much = 3.0 / 4.0 / 5.0; 
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Whether this is equal to 0.15 or 3.75 depends on which division operator gets to grab the num- 
ber 4 . 0 first. There is an exhaustive list of rules of associativity in the online manual, but the rule 
to remember is that associativity is usually left-before-right — that is, the preceding expression 
would evaluate to 0.15, because the leftmost of the two division operators wins the dispute over 
precedence. 

The final wrinkle is order of evaluation, which is not quite the same thing as associativity. For 
example, look at the arithmetic expression: 

3*4 + 5*6 

We know that the multiplications will happen before the additions, but that is not the same as 
knowing which multiplication PHP will perform first. In general, you need not worry about evalua- 
tion order, because in almost all cases it will not affect the result. You can construct weird examples 
where the result does depend on order of evaluation, usually by making assignments in subexpres- 
sions that are used in other parts of the expression. For example: 

$huh = ($this = $that + 5) + ($that = $this + 3); // BAD 

But don't do this, okay? PHP may or may not have a predictable order of evaluation of expressions, 
but you shouldn't depend on it — so we're not going to tell you! (The one legitimate use of relying on 
left-to-right evaluation order is in short-circuiting Boolean expressions, which we cover in Chapter 5.) 

Expressions and types 

Usually, the programmer is careful to match the types of expressions with the operators and func- 
tions that combine them. Common expressions are mathematical (with mathematical operators 
combining numbers) or Boolean (combining true-or-false statements with ands and ors) or string 
expressions (with operators and functions constructing strings of characters). As with the rest of PHP, 
however, the treatment of types is surprisingly forgiving. Consider the following expression, which 
deliberately mixes the types of subexpressions in an inappropriate way: 

2 + 2 * "nonsense" + TRUE 

Rather than produce an error, this evaluates to the number 3. (You can take this as a puzzle for now, 
but we will explain how such a thing can happen in the "Types in PHP" section of this chapter.) 

Assignment expressions 

A very common kind of expression is the assignment, where a variable is set to equal the result of 
evaluating some expression. These have the form of a variable name (which always starts with a $), 
followed by a single equal sign, followed by the expression to be evaluated. For example: 

$eight = 2 * (2 * 2) ; 
assigns the variable $ei ght the value you would expect. 
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An important thing to remember is that even assignment expressions are expressions and so have val- 
ues themselves! The value of an expression that assigns a variable is the same as the value assigned. 
This means that you can use assignment expressions in the middle of more complicated expressions. 
If you evaluate the statement: 

$ten = ($two = 2) + ($eight = 2 * (2 * 2)); 
each variable would be assigned a numerical value equal to its name. 



Reasons for expressions and statements 

There are usually only two reasons to write an expression in PHP: for its value or for a side effect. The 
value of an expression is passed on to any more complicated expression that includes it; side effects 
are anything else that happens as a result of the evaluation. The most typical side effects involve 
assigning or changing a variable, printing something to the user's screen, or making some other per- 
sistent change to the program's environment (such as interacting with a database). 

Although statements are expressions, they are not themselves included in more complicated expres- 
sions. This means that the only good reason for a statement is a side effect! It also means that it is 
possible to write legal (yet totally useless statements) such as the second of these: 

pri nt( "Hel 1 o" ) ; // side effect is printing to screen 

2*3+4; // useless - no side effect 

$value_num =3*4+5; // side effect is assignment 

store_i n_database ( 49 . 5 ) ; // side effect to DB 



Braces make blocks 

Although statements cannot be combined like expressions, you can always put a sequence of state- 
ments anywhere a statement can go by enclosing them in a set of curly braces. 

For example, the i f construct in PHP has a test (in parentheses) followed by the statement that 
should be executed if the test is true. If you want more than one statement to be executed when the 
test is true, you can use a brace-enclosed sequence instead. The following pieces of code (which sim- 
ply print a reassuring statement that it is still true that 1 + 2 is equal to 3) are equivalent: 

if (3 == 2 + 1) 

print("Good - I haven't totally lost my mind.<BR>"); 



if (3 == 2 + 1) 
t 

print("Good - I haven't totally "); 
pri nt( "lost my mi nd . <BR> " ) ; 

1 
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You can put any kind of statement in a brace-enclosed block, including, say, an i f statement that 
itself has a brace-enclosed block. This means that i f statements can have other i f statements inside 
them. In fact, this kind of nesting can be done to an arbitrary number of levels. 

Comments 

A comment is the portion of a program that exists only for the human reader. The very first thing that 
a program executor does with program code is to strip out the comments, so they cannot have any 
effect on what the program does. Comments are invaluable in helping the next person who reads 
your code figure out what you were thinking when you wrote it, even when that person is yourself a 
week from now. 

PHP drew its inspiration from several different programming languages, most notably C, Perl, and 
Unix shell scripts. As a result, PHP supports styles of comments from all those languages, and those 
styles can be intermixed freely in PHP code. 

C-style multiline comments 

The multiline style of commenting is the same as in C: A comment starts with the character pair /* 
and terminates with the character pair * / . For example: 

/* This is 

a comment in 
PHP */ 

The most important thing to remember about multiline comments is that they cannot be nested. 
You cannot put one comment inside another. If you try, the comment will be closed off by the first 
instance of the */ character pair, and the rest of what was intended to be an enclosing comment will 
instead be interpreted as code, probably failing horribly. For example: 

/* This comment will /* fail horribly on the 
last word of this */ sentence 

*/ 

This is an easy thing to do unintentionally, usually when you try to deactivate a block of commented 
code by "commenting it out." 

Single-line comments : # and // 

In addition to the /* ... */ multiple-line comments, PHP supports two different ways of comment- 
ing to the end of a given line: one inherited from C++ and Java and the other from Perl and shell 
scripts. The shell-script-style comment starts with a pound sign, whereas the C++ style comment 
starts with two forward slashes. Both of them cause the rest of the current line to be treated as a 
comment, as in the following: 

# This is a comment, and 
# this is the second line of the comment 
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// This is a comment too. Each style comments only 
// one line so the last word of this sentence will fail 
horri bl y . 

The very alert reader might argue that single-line comments are incompatible with what we said 
earlier about whitespace insensitivity. That would be correct — you will get a very different result if 
you take a single-line comment and replace one of the spaces with an end-of-line character. A more 
accurate way of putting it is that, after the comments have been stripped out of the code, PHP code 
is whitespace insensitive. 



Variables 

The main way to store information in the middle of a PHP program is by using a variable — a way to 
name and hang on to any value that you want to use later. 

Here are the most important things to know about variables in PHP (more detailed explanations 
will follow): 

■ All variables in PHP are denoted with a leading dollar sign ($). 

■ The value of a variable is the value of its most recent assignment. 

■ Variables are assigned with the = operator, with the variable on the left-hand side and the 
expression to be evaluated on the right. 

■ Variables can, but do not need, to be declared before assignment. 

■ Variables have no intrinsic type other than the type of their current value. 

■ Variables used before they are assigned have default values. 

PHP variables are Perl-like 

All variables in PHP start with a leading $ sign just like scalar variables in the Perl scripting lan- 
guage, and in other ways they have similar behavior (need no type declarations, may be referred to 
before they are assigned, and so on). (Perl hackers may need to do no more than skim the headings 
of this section, which is really for the rest of us.) 

After the initial $ , variable names must be composed of letters (uppercase or lowercase), digits (0-9), 
and underscore characters (_). Furthermore, the first character after the $ may not be a number. 

Declaring variables (or not) 

This subheading is here simply because programmers from some other languages might be looking for 
it — in languages such as C, C++, and Java, the programmer must declare the name and type of any 
variable before making use of it. However in PHP, because types are associated with values rather than 
variables, no such declaration is necessary — the first step in using a variable is to assign it a value. 
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Assigning variables 

Variable assignment is simple — just write the variable name, and add a single equal sign (=); then 
add the expression that you want to assign to that variable: 

$pi = 3 + 0.14159; // approximately 

Note that what is assigned is the result of evaluating the expression, not the expression itself. After 
the preceding statement is evaluated, there is no way to tell that the value of $pi was created by 
adding two numbers together. 

It's conceivable that you will want to actually print the preceding math expression rather than evalu- 
ate it. You can force PHP to treat a mathematical variable assignment as a string by quoting the 
expression: 

$pi = "3 + 0.14159" ; 



Reassigning variables 

There is no interesting distinction in PHP between assigning a variable for the first time and chang- 
ing its value later. This is true even if the assigned values are of different types. For example, the fol- 
lowing is perfectly legal: 

$my_num_va r = "This should be a number - hope it's reassigned"; 
$my_num_var = 5; 

If the second statement immediately follows the first one, the first statement has essentially no effect. 



Unassigned variables 



Many programming languages will object if you try to use a variable before it is assigned; others 
will let you use it, but if you do you may find yourself reading the random contents of some area of 
memory. In PHP, the default error-reporting setting allows you to use unassigned variables without 
errors, and PHP ensures that they have reasonable default values. 



CROSS-REF 



If you would like to be warned about variables that have not been assigned, you should 
change the error-reporting level to E__ALL (the highest level possible) from the default level 
of error reporting. You can do this either by including the statement error_reporti ng ( E_ALL ) ; at 
the top of a script or by changing your php . i n i file to set the default level (see Chapters 29 and 30). 



Default values 

Variables in PHP do not have intrinsic types — a variable does not know in advance whether it will 
be used to store a number or a string of characters. So how does it know what type of default value 
to have when it hasn't yet been assigned? 
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The answer is that, just as with assigned variables, the type of a variable is interpreted depend- 
ing on the context in which it is used. In a situation where a number is expected, a number will be 
produced, and this works similarly with character strings. In any context that treats a variable as a 
number, an unassigned variable will be evaluated as 0; in any context that expects a string value, an 
unassigned variable will be the empty string (the string that is zero characters long). 

Checking assignment with isset 

Because variables do not have to be assigned before use, in some situations you can actually convey 
information by selectively setting or not setting a variable! PHP provides a function called isset 
that tests a variable to see whether it has been assigned a value. 

As the following code illustrates, an unassigned variable is distinguishable even from a variable that 
has been given the default value: 

$set_var = 0; //set_var has a value 

//never_set does not 
pri nt ( " set_va r print value: $set_var<BR>" ) ; 
pri nt ( " never_set print value: $never_set<BR> " ) ; 
if ($set_var == $never_set) 

pri nt ( " set_va r is equal to never_set ! <BR>" ) ; 
if ( i sset ( $set_va r ) ) 

pri nt ( " set_va r is set.<BR>"); 
else 

pri nt ( " set_va r is not set.<BR>"); 
if ( i sset ( $never_set ) ) 

pri nt( "never_set is set.<BR>"); 

else 

pri nt( "never_set is not set."); 
Oddly enough, this code will produce the following output: 

set_var print value: 0 
never_set print value: 
set_var is equal to never_set! 
set_var is set. 
never_set is not set. 

The variable $ n e v e r_s e t has never been assigned, so it produces an empty string when a string is 
expected (as in the print statement) and a zero value when a number is expected (as in the com- 
parison test that concludes that the two variables are the same). Still, isset can tell the difference 
between $set_var and $never_set. 

Assigning a variable is not irrevocable — the function u n s e t ( ) will restore a variable to an unas- 
signed state (for example, unset ( $set__va r ) ; will make $set_va r into an unbound variable, 
regardless of its previous assignments). 
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Variable scope 

Scope is the technical term for the rules about when a name (for, say, a variable or function) has the 
same meaning in two different places and in what situations two names spelled exactly the same 
way can actually refer to different things. 

Any PHP variable not inside a function has global scope and extends throughout a given "thread" of 
execution. In other words, if you assign a variable near the top of a PHP file, the variable name has 
the same meaning for the rest of the file; and if it is not reassigned, it will have the same value as the 
rest of your code executes (except inside the body of functions and classes). 

The assignment of a variable will not affect the value of variables with the same name in other 
PHP files or even in repeated uses of the same file. For example, let's say that you have two files, 
startup. php and next_thing.php, which are typically visited in that order by a user. Let's also 
say that near the top of startup. php, you have the line: 

$username = "Jane Q. User"; 

which is executed only in certain situations. Now, you might hope that, after setting that variable in 
startup. php, it would also be preset automatically when the user visited next_thing.php, but 
no such luck. Each time a PHP page executes, it assigns and reassigns variables as it goes, and those 
variables disappear at the end of a page's production. Assignments of variables in one file do not 
affect variables of the same name in a different file or even in other requests for the same file. 

Obviously, there are many situations in which you would like to hold onto information for longer 
than it takes to generate a particular web page. There are a variety of ways you can accomplish this, 
and the different techniques are a lot of what the rest of this book is about. For example, you can 
pass information from page to page using GET and POST variables (Chapter 6), store information 
persistently in a database (all of Part II of this book), associate it with a user's session using PHP's 
session mechanism (see Chapter 24), or store it on a user's hard disk via a cookie (see Chapter 24). 

Functions and variable scope 

Except inside the body of a function, variable scope in PHP is quite simple: Within any given execu- 
tion of a PHP file, just assign a variable, and its value will be there for you later. We haven't yet cov- 
ered how to define your own functions, but it's worth a look-ahead note: Variables assigned within 
a function are local to that function, and unless you make a special declaration in a function, that 
function won't have access to the global variables defined outside the function, even when they are 
defined in the same file. (We will discuss the scope of variables in functions in depth when we cover 
function definitions in Chapter 5.) 

You can switch modes if you want 

One scoping question that we had the first time we saw PHP code was: Does variable scope persist 
across tags? For example, we have a single file that looks like: 

<HTML> 
<HEAD> 
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<?php 

$username = "Jane Q. User"; 

?> 

</HEAD> 
<B0DY> 
< ? p h p 

print("$usernanie<BR>"); 

?> 

</B0DY> 
</HTML> 

Should we expect our assignment to Susername to survive through the second of the two PHP- 
tagged areas? The answer is yes — variables persist throughout a thread of PHP execution (in other 
words, through the whole process of producing a web page in response to a user's request). This is 
a single manifestation of a general PHP rule, which is that the only effect of the tags is to let the PHP 
engine know whether you want your code to be interpreted as PHP or passed through untouched as 
HTML. You should feel free to use the tags to switch back and forth between modes whenever it is 
convenient. 

Constants 

In addition to variables, which may be reassigned, PHP offers constants, which have a single value 
throughout their lifetime. Constants do not have a $ before their names, and by convention the 
names of constants usually are in uppercase letters. Constants can contain only scalar values (num- 
bers and string). Constants have global scope, so they are accessible everywhere in your scripts after 
they have been defined — even inside functions. 

For example, the built-in PHP constant E_ALL represents a number that indicates to the error_ 
report ing( ) function that all errors and warnings should be reported. A call to erro ^report- 
ing ( ) might look like this: 

error_reporti ng ( E_ALL ) ; 

This is identical to calling error_reporti ng ( ) on the integer value of E_ALL, but is better because 
the actual value of E_A L L may change from one version of PHP to the next. 

It's also possible to create your own constants using the def i ne ( ) function. The code: 
define(MY^ANSWER, 42); 

would cause MY_ANSWER to evaluate to 42 everywhere it appears in your code. There is no way to 
change this assignment after it has been made, and like variables, user-defined constants that are 
not part of PHP itself do not persist across pages unless they are explicitly passed to a new page. 
When created constants are used, they are generally most usefully defined in an external include file 
and might be used for such information as a sales-tax rate or perhaps an exchange rate. 
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Types in PHP; Don't Worry, Be Happy 

All programming languages have some kind of type system, which specifies the different kinds of 
values that can appear in programs. These different types often correspond to different bit-level rep- 
resentations in computer memory, although in many cases programmers are insulated from having 
to think about (or being able to mess with) representations in terms of bits. 

PHP's type system is simple, streamlined, and flexible, and it insulates the programmer from low-level 
details. PHP makes it easy not to worry too much about typing of variables and values, both because it 
does not require variables to be typed and because it handles a lot of type conversions for you. 

No variable type declarations 

As you saw in Chapter 3, the type of a variable does not need to be declared in advance. Instead, the 
programmer can jump right ahead to assignment and let PHP take care of figuring out the type of 
the expression assigned: 

$f i rst_number = 55.5; 

$second_number = "Not a number at all"; 

Automatic type conversion 

PHP does a good job of automatically converting types when necessary. Like most other modern 
programming languages, PHP will do the right thing when, for example, doing math with mixed 
numerical types. The result of the expression 

$pi = 3 + 0.14159; 

is a floating-point (double) number, with the integer 3 implicitly converted into floating point before 
the addition is performed. 

Types assigned by context 

PHP goes further than most languages in performing automatic type conversions. Consider: 

$sub = substr(12345, 2, 2) ; 
print("sub is $sub<BR>"); 

The substr function is designed to take a string of characters as its first input and return a sub- 
string of that string, with the start point and length determined by the next two inputs to the func- 
tion. Instead of handing the function a character string, however, we gave it the integer 12345. What 
happens? As it turns out, there is no error, and we get the browser output: 

sub is 34 

Because substr expects a character string rather than an integer, PHP converts the number 12345 
to the character string ' 12345 ' , which substr then slices and dices. 
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Because of this automatic type conversion, it is very difficult to persuade PHP to give a type error — 
in fact, PHP programmers need to exercise a little care sometimes to make sure that type confusions 
do not lead to error-free but unintended results. 



Type Summary 

PHP has a total of eight types: integers, doubles, Booleans, strings, arrays, objects, NULL, and resources. 

■ Integers are whole numbers, without a decimal point, like 495. 

■ Doubles are floating-point numbers, like 3.14159 or 49.0. 

■ Booleans have only two possible values: TRUE and FALSE. 

■ NULL is a special type that only has one value: NULL. 

■ Strings are sequences of characters, like 'PHP 4.0 supports string operati ons . ' 

■ Arrays are named and indexed collections of other values. 

■ Objects are instances of programmer-defined classes, which can package up both other 
kinds of values and functions that are specific to the class. 

■ Resources are special variables that hold references to resources external to PHP (such as 
database connections). 

Of these, the first five are simple types, and the next two (arrays and objects) are compound — the 
compound types can package up other arbitrary values of arbitrary type, whereas the simple types 
cannot. We treat only the simple types in this chapter, since arrays (see Chapter 8) and objects (see 
Chapter 20) need chapters all to themselves. Finally, the thorniest details of the type system, includ- 
ing discussion of the resource type, are deferred to Chapter 25. 



The Simple Types 

The most of the simple types in PHP (integers, doubles, Booleans, NULL, and strings) should be familiar 
to those with programming experience (although we will not assume that experience and will explain 
them in detail). The only thing likely to surprise C programmers is how few types there are in PHP. 

Many programming languages have several different sizes of numerical types, with the larger ones 
allowing a greater range of values, but also taking up more room in memory. For example, the C lan- 
guage has a short type (for relatively small integers), along type (for possibly larger integers), and 
an i nt type (which might be intermediate, but in practice is sometimes identical either to the short 
or long type). It also has floating-point types, which vary in their precision. This kind of typing 
choice made sense in an era when tradeoffs between memory use and functionality were often ago- 
nizing. The PHP designers made what we think is a good decision to simplify this by having only 
two numerical types, corresponding to the largest of the integral and floating-point types in C. 



46 



Learning PHP Syntax and Variables 



Integers 

Integers are the simplest type — they correspond to simple whole numbers, both positive and nega- 
tive. Integers can be assigned to variables, or they can be used in expressions, like this: 

$int_var = 12345; 

$another_int = -12345 + 12345; // will equal zero 

Read formats 

Integers can actually be read in three formats, which correspond to bases: decimal (base 10), octal 
(base 8), and hexadecimal (base 16). Decimal format is the default, octal integers are specified with 
a leading 0, and hexadecimals have a leading Ox. Any of the formats can be preceded by a - sign to 
make the integer negative. For example: 

$integer_10 = 1000; 

$integer_8 = -01000; 

$integer_16 = 0x1000; 

pri nt ( " i nteger_10 : $i nteger_10<BR>" ) ; 

pri nt ( " i nteger_8 : $i nteger_8<BR> " ) ; 

pri nt ( " i nteger_16 : $ i nteger_16<BR>" ) ; 

yields the browser output: 

integer_10: 1000 
integer_8: -512 
integer_16: 4096 

Note that the read format affects only how the integer is converted as it is read — the value stored in 
$ i n t e g e r_8 does not remember that it was originally written in base 8. Internally, of course, these 
numbers are represented in binary format; we see them in their base 10 conversion in the preceding 
output because that is the default for printing and incorporating i nt variables into strings. 

Range 

How big (or small) can integers get? Because PHP integers correspond to the C 1 ong type, which 
in turn depends on the word-size of your machine, this is difficult to answer definitively. For most 
common platforms, however, the largest integer is 2 31 - 1 (or 2,147,483,647), and the smallest (most 
negative) integer is -(2 31 - 1) (or -2,147,483,647). 

The PHP constant PH P I NT_MAX will tell you the maximum integer for your implementation. If you 

really need integers even larger or smaller than the preceding, PHP does have some arbitrary-preci- 
sion functions — see the BC section of the "Mathematics" chapter (see Chapter 27). 

Doubles 

Doubles are floating-point numbers, such as: 
$fi rst_doubl e = 123.456; 
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$second_doubl e = 0.456; 
$even_doubl e = 2.0; 

Note that the fact that $even_doubl e is a "round" number does not make it an integer. Integers and 
doubles are stored in different underlying formats, and the result of: 

$five = $even_double + 3; 

is a double, not an integer, even if it prints as 5. In almost all situations, however, you should feel 
free to mix doubles and integers in mathematical expressions, and let PHP sort out the typing. 

By default, doubles print with the minimum number of decimal places needed — for example, the code: 

$many = 2.2888800; 
$many_2 = 2.2111200; 
$few = $many + $many_2; 
print("$many + $many_2 = $few<BR>"); 

produces the browser output: 

2.28888 + 2.21112 = 4.5 

■ (■• rj fj j r V" If you need finer control of printing, see the pri ntf function in Chapter 7. 

Read formats 

The typical read format for doubles is - X . Y , where the - optionally specifies a negative number, and 
both X and Y are sequences of digits between 0 and 9. The X part may be omitted if the number is 
between -1.0 and 1.0, and the Y part can also be omitted. Leading or trailing zeros have no effect. 
All the following are legal doubles: 

$smal ^positive = 0.12345; 
$smal l_negati ve = -.12345; 
$even_double = 2.00000; 
$sti 1 l_doubl e = 2. ; 

In addition, doubles can be specified in scientific notation, by adding the letter e and a desired 
integral power of 10 to the end of the previous format — for example, 2 . 2e-3 would correspond 
to 2.2 x 10 J . The floating-point part of the number need not be restricted to a range between 1.0 
and 10.0. All the following are legal: 

$smal 1 _pos i ti ve = 5.5e-3; 

pri nt( "smal l_posi ti ve is $smal l_posi ti ve<BR>" ) ; 
$1 a rge_posi ti ve = 2.8e+16; 

pri nt( "1 arge_posi ti ve is $1 arge_posi ti ve<BR>" ) ; 
$smal l_negative = -2222e-10; 

pri nt( "smal l_negati ve is $smal l_negati ve<BR>" ) ; 
$1 arge_negative = -0.00189e6; 

pri nt( "1 arge_negati ve is $1 arge_negati ve<BR>" ) ; 
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The preceding code produces the following browser output: 

smal l_posi ti ve is 0.0055 

1 a rge_pos i ti ve is 2.8E+16 

smal l_negati ve is -2.222E-07 

1 arge_negati ve is -1890 

Notice that, just as with octal and hexadecimal integers, the read format is irrelevant once PHP has 
finished reading in the numbers — the preceding variables retain no memory of whether or not 
they were originally specified in scientific notation. In printing the values, PHP is making its own 
decisions to print the more extreme values in scientific notation, but this has nothing to do with the 
original read format. 

Booleans 

Booleans are true-or-false values, which are used in control constructs like the testing portion of 
an i f statement. As you will see in Chapter 5, Boolean truth values can be combined using logical 
operators to make more complicated Boolean expressions. 

Boolean constants 

PHP provides a couple of constants especially for use as Booleans: TRUE and FALSE, which can be 
used like this: 

if (TRUE) 

print("This will always print<BR>"); 
else 

print("This will never print<BR>"); 

Interpreting other types as Booleans 

Here are the rules for determine the "truth" of any value not already of the Boolean type: 

■ If the value is a number, it is false if the number is zero and true otherwise. 

■ If the value is a string, it is false if the string is empty (has zero characters) or is the string 
" 0 " , and is true otherwise. 

■ Values of type NULL are always false. 

■ If the value is a compound type (an array or an object), it is false if it contains no other val- 
ues, and it is true otherwise. For an object, containing a value means having a member vari- 
able that has been assigned a value. 

■ Valid resources are true (although some functions that return resources when they are suc- 
cessful will return FALSE when unsuccessful). 



CROSS-REF 



For a more complete account of converting values across types, see Chapter 25. 
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Examples 

Each of the following variables has the truth value embedded in its name when it is used in a 
Boolean context. 

$true_num = 3 + 0.14159; 
$true_str = "Tried and true"; 

$true_array[49] = "An array element"; // see next section 
$false_array = arrayO; 
$false_null = NULL; 
$false_num = 999 - 999; 

$false_str = ""; // a string zero characters long 



Don't use doubles as Booleans 

Note that, although Rule 1 implies that the double 0.0 converts to a false Boolean value, it is danger- 
ous to use floating-point expressions as Boolean expressions, because of possible rounding errors. 
For example: 

$floatbool = sqrt(2.0) * sqrt(2.0) - 2.0; 
if ($floatbool ) 

pri nt ( " Fl oati ng-poi nt Booleans are dangerous ! <BR>" ) ; 
else 

print("It worked ... this time.<BR>"); 
print("The actual value is $floatbool<BR>"); 

The variable $f 1 oatbool is set to the result of subtracting two from the square of the square root of 
two — the result of this calculation should be equal to zero, which means that $f 1 oatbool is false. 
Instead, the browser output we get is: 

Floating-point Booleans are dangerous! 
The actual value is 4 . 4408920985006E- 16 

The value of$floatbool is very close to 0.0, but it is nonzero and, therefore, unexpectedly true. 
Integers are much safer in a Boolean role — as long as their arithmetic happens only with other inte- 
gers and stays within integral sizes, they should not be subject to rounding errors. 



NULL 

The world of Booleans may seem small, since the Boolean type has only two possible values. The 
NULL type, however, takes this to the logical extreme: The type NULL has only one possible value, 
which is the value NULL. To give a variable the NULL value, simply assign it like this: 

$my_var = NULL; 

The special constant NU LL is capitalized by convention, but actually it is case insensitive; you could 
just as well have typed: 

$my_va r = null; 
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So what is special about NULL? NULL represents the lack of a value. (You can think of it as the non- 
value or the unvalued) A variable that has been assigned the value N U L L is nearly indistinguishable 
from a variable that has not been set at all. In particular, a variable that has been assigned NULL has 
the following properties: 

■ It evaluates to FALSE in a Boolean context. 

■ It returns FALSE when tested with I s Set ( ) . (No other type has this property.) 

■ PHP will not print warnings if you pass the variable to functions and back again, whereas 
passing a variable that has never been set will sometimes produce warnings. 

The NULL value is best used for situations where you want a variable not to have a value, intention- 
ally, and you want to make it clear to both a reader of your code and to PHP that this is what you 
want. The latter point is particularly relevant when passing variables to functions. 

For example, the following pseudocode may print a warning (depending on your error-reporting 
settings) if the variable $authorization has never been assigned before you pass it to your test_ 
authorization( ) function. 

if ( test_authori za ti on ( $authori za ti on ) ) ( 

// code that grants a privilege of some sort 

} 

On the other hand, code like this: 
$authori zati on = NULL; 

// code that might or might not set Sauthori zati on 
if ( test_authori zati on ( Sauthori zati on ) ) ( 

// code that grants a privilege of some sort 

1 

does not cause an unbound- variable warning, assuming that you have written test_authori za- 
ti on ( ) to handle arguments that might be NULL. It also makes clear to a reader of the code that 
you intend for the variable to lack a value unless there's a case where it is assigned. 

Strings 

Strings are character sequences, as in the following: 

$string_l = "This is a string in double quotes."; 
$string_2 = 'This is a somewhat longer, singly quoted string'; 
$string_39 = "This string has thirty -nine characters."; 
$string_0 = ""; // a string with zero characters 

Strings can be enclosed in either single or double quotation marks, with different behavior at read 
time. Singly quoted strings are treated almost literally, whereas doubly quoted strings replace vari- 
ables with their values as well as specially interpreting certain character sequences. 
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Singly quoted strings 

Except for a couple of specially interpreted character sequences, singly quoted strings read in and 
store their characters literally. The following code: 

$literally = 'My $variable will not print!\\n'; 
printdliterally); 

produces the browser output: 

My $variable will not print!\n 

Singly quoted strings also respect the general rule that quotation marks of a different type will not 
break a quoted string. This is legal: 

$s i ngl y„quoted = 'This quote mark: " is no big deal'; 

To embed a single quotation mark (such as an apostrophe) in a singly quoted string, escape it with a 
backslash, as in the following: 

$s i ngl y_quoted = 'This quote mank\'s no big deal either'; 

Although in most contexts backslashes are interpreted literally in singly quoted strings, you may 
also use two backslashes (\ \) as an escape sequence for a single (nonescaping) backslash. This is 
useful when you want a backslash as the final character in a string, as in: 

$win_path = ' C : \\ Inet PubW PHP\ \ ' ; 

print("A Wi ndows - sty 1 e pathname: $wi n_path<BR>" ) ; 

which is displayed as: 

A Wi ndows - sty 1 e pathname: C:\InetPub\PHP\ 

r- jsj r^" j'f"'"' [ ^ e could nave use{ l single backslashes to produce the first two backslashes in the output, 
■■ but the escaping is necessary at the end of the string so that the closing quotation mark 

will not be escaped. 



These two escape sequences (\ \ and \ ' ) are the only exceptions to the literal-mindedness of singly 
quoted strings. 



Doubly quoted strings 

Strings that are delimited by double quotes (as in "this") are preprocessed in both the following 
two ways by PHP: 

■ Certain character sequences beginning with backslash (\) are replaced with special 
characters. 

■ Variable names (starting with $) are replaced with string representations of their values. 
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The escape-sequence replacements are: 

■ \ n is replaced by the newline character 

■ \ r is replaced by the carriage-return character 

■ \ t is replaced by the tab character 

■ \ $ is replaced by the dollar sign itself ($) 

■ \ " is replaced by one double quotation mark (") 

■ \ \ is replaced by a single backslash (\) 

The first three of these replacements make it easy to visibly include certain whitespace characters 
in your strings. The \ $ sequence lets you include the $ symbol when you want it, without it being 
interpreted as the start of a variable. The \ " sequence is there so that you can include a double quo- 
tation mark symbol without terminating your doubly quoted string. Finally, because the \ character 
starts all these sequences, you need a way to include that character literally, without it starting an 
escape sequence — to do this, you preface it with itself. 

Just as with singly quoted strings, quotes of the opposite type can be freely included without an 
escape character: 

$has_apostrophe = "There's no problem here"; 

Single versus double quotation marks 

PHP does some preprocessing of doubly quoted strings (strings with quotation marks like "this") 
before constructing the string value itself. For one thing, variables are replaced by their values (as in 
the preceding example). To see that this replacement is really about the quoted string rather than the 
print construct, consider the following code: 

$animal = "antelope"; // first assignment 
$saved_stri ng = "The animal is $ani mal <BR>" ; 
$animal = "zebra"; // reassignment 

print("The animal is $animal <BR>" ) ; //first display line 
pri nt ( $sa ved_st r i ng ) ; //second display line 

What output would you expect here? As it turns out, your browser would display: 

The animal is zebra 
The animal is antelope 

And the browser displays the preceding output in exactly that order. This is because "antelope" 
is spliced into the string $saved_string, before the $ a n i m a 1 variable is reassigned. In addition to 
splicing variable values into doubly quoted strings, PHP also replaces some special multiple-char- 
acter escape sequences with their single-character values. The most commonly used is the end-of-line 
sequence (" \n ") — in reading a string like: 

"The first line \n\n\nThe fourth line" 



53 



Part I 



Introducing PHP 



Variable interpolation 

Whenever an unescaped $ symbol appears in a doubly quoted string, PHP tries to interpret what 
follows as a variable name and splices the current value of that variable into the string. Exactly what 
kind of substitution occurs depends on how the variable is set: 

■ If the variable is currently set to a string value, that string is interpolated (or spliced) into 
the doubly quoted string. 

■ If the variable is currently set to a nonstring value, the value is converted to a string, and 
then that string value is interpolated. 

■ If the variable is not currently set, PHP interpolates nothing (or, equivalently, PHP splices 
in the empty string). 

For example: 

$ t h i s = "this"; 
$that = "that"; 
$the_other = 2.2000000000; 

pri nt( "$thi s , $not_set , $that+$the_other<BR>" ) ; 
produces the PHP output 

this, ,that+2.2<BR> 
which in turn, when seen in a browser, looks like: 

this, ,that+2.2 

If you find any part of this example puzzling, it is worth working through exactly what PHP does to 
parse the string in the print statement. First, notice that the string has four $ signs, each of which 
is interpreted as starting a variable name. These variable names terminate at the first occurrence of a 
character that is not legal in a variable name. Legal characters are letters, numbers, and underscores; 
the illegal terminating characters in the preceding print string are (in order) a comma, another 
comma, the plus symbol (+), and a left angle bracket (<). The first two variables are bound to strings 
('this' and 'that'), so those strings are spliced in literally. The next variable ($ n ot_s et) has 
never been assigned, so it is omitted entirely from the string under construction. Finally, the last 
variable ($the_other) is discovered to be bound to a double — that value is converted to a string 
("2.2 "), which is then spliced into our constructed string. 

fC T * riC C* \i- f "' r " ^ or more about converting numbers to strings, see the "Assignment and Coercion" sec- 
^J-^^-J-jrr tion in chapter 25. 

As we said earlier in this chapter, all this interpretation of doubly quoted strings happens when 
the string is read, not when it is printed. If we saved the example string in a variable and printed 
it out later, it would reflect the variable values in the preceding code even if the variables had been 
changed in the meantime. 
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rytj £lii-' I ^ f* '? ac ' c '' t ' on to sm g' e quotation marks and double quotation marks, there is another way 
-~ — to create strings (called the heredoc syntax), which in some ways makes it even easier to 

splice in the values of variables. We cover it in Chapter 7. 

Newlines in strings 

Although PHP offers an escape sequence (\n) for newline characters, it is good to know that you 
can literally include new lines in the middle of strings, which PHP also treats as a newline charac- 
ters. This capability turns out to be convenient when creating HTML strings, because browsers will 
ignore the line breaks anyway, so you can format your strings with line breaks to make your PHP 
code lines short: 

print("<HTMLXHEADX/HEADXBODY>My HTML page is too big 
to fit on a single line, but that doesn't mean that I 
need multiple print statements ! </BODYX/HTML>" ) ; 

We produced this statement in our text editor by literally hitting the Enter key at the end of the first 
two lines — these newlines are preserved in the string, so the single print statement will produce 
three distinct lines of PHP output. (Your mileage may vary depending on your text editor — if your 
editor automatically wraps lines in displaying them, you may see three lines of code that are actu- 
ally one long line.) Of course, the browser program will ignore these newlines and will make its own 
decisions about whether and where to break the lines in display, but you will see the linebreaks if 
you use View Source in your browser to see the HTML itself. 

Limits 

There are no artificial limits on string length — within the bounds of available memory, you ought 
to be able to make arbitrarily long strings. 

Output 

Most of the constructs in the PHP language execute silently — they don't print anything to output. 
The only way that your embedded PHP code will display anything in a user's browser program is 
either by means of statements that print something to output or by calling functions that, in turn, 
call print statements. 

Echo and print 

The two most basic constructs for printing to output are echo and print. Their language status 
is somewhat confusing, because they are basic constructs of the PHP language, rather than being 
functions. As a result, they can be used either with parentheses or without them. (Function calls 
always have the name of the function first, followed by a parenthesized list of the arguments to the 
function.) 
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Echo 

The simplest use of echo is to print a string as argument, for example: 

echo "This will print in the user's browser window."; 
Or equivalently: 

echo("This will print in the user's browser window."); 

Both of these statements will cause the given sentence to be displayed, without displaying the quote 
signs. (Note for C programmers: Think of the HTTP connection to the user as the standard output 
stream for these functions.) 

You can also give multiple arguments to the unparenthesized version of echo, separated by commas, 
as in: 

echo "This will print in the ", "user's browser window."; 
The parenthesized version, however, will not accept multiple arguments: 
echo ("This will produce a ", "PARSE ERROR!"); 

Print 

The command print is very similar to echo, with two important differences: 

■ Unlike echo, print can accept only one argument. 

■ Unlike echo, print returns a value, which represents whether or not the print statement 
succeeded. 

The value returned by p r i n t is always 1 . 

Both echo and print are usually used with string arguments, but PHP's type flexibility means that 
you can throw pretty much any type of argument at them without causing an error. For example, the 
following two lines will print exactly the same thing: 

print( "3. 14159" ) ; // print a string 
pri nt ( 3 . 14159 ) ; // print a number 

Technically, what is happening in the second line is that, because print expects a string argument, 
the floating-point version of the number is converted to a string value before print gets hold of it. 
However, the effect is that both print and echo will reliably print out numbers as well as string 
arguments. 

For the sake of simplicity and uniformity, we will typically use the parenthesized version of p r i n t 
in our examples, rather than using echo. 
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p>j>j>'"p__ r| pjf In addition to the printing functions discussed here, there are two primary printing func- 
"~' J ~ U — tions used mostly for debugging: p r i n t_r ( ) and v a r_d limp ( ) . The point of these func- 
tions is to help you visualize what's going on with compound data structures like arrays, so we cover 
them along with the details of arrays in Chapter 8. 

Variables and strings 

C programmers are accustomed to using a function called pri ntf , which allows you to splice values 
and expressions into a specially formatted printing string. PHP has analogous functions (which we 
will cover in Chapter 6), but as it turns out we can get much of the same functionality just by using 
pri nt (or echo) with quoted strings. For example, the fragment: 

$animal = "antelope"; 
$animal_heads = 1; 
$animal_l egs = 4; 

print("The $animal has $animal_heads head( s ) . <BR>" ) ; 
print("The $animal has $ani mal _1 egs 1 eg ( s ) . <BR> " ) ; 

will produce the following output in the browser: 

The antelope has 1 head(s). 
The antelope has 4 leg(s). 

The values for the variables we included in the string have been neatly spliced into the printed out- 
put. This makes it very easy to quickly produce web pages with content that varies depending on 
how variables have been set. It is not the result of any magical properties of p r i n t , however — the 
magic is really happening in the interpretation of the quoted string itself. 

HTML and linebreaks 

One mistake often made by new PHP programmers (especially those from a C background) is to 
try to break lines of text in their browsers by putting end-of-line characters ( " \ n " ) in the strings 
they print. To understand why this doesn't work, you have to distinguish the output of PHP (which 
is usually HTML code, ready to be sent over the Internet to a browser program) from the way that 
output is rendered by the user's browser. Most browser programs will make their own choices about 
how to split up lines in HTML text, unless you force a line break with the < B R> tag. End-of-line 
characters in strings will put line breaks in the HTML source that PHP sends to your user's browser 
(which can still be useful for creating readable HTML source), but they will usually have no effect on 
the way that text looks in a web page. 



Summary 

PHP code follows a basic set of syntactical rules, mostly borrowed from programming languages 
such as C and Perl. The syntactical requirements of PHP are minimal, and in general PHP tries to 
display results when it can rather than generating an error. 
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PHP has eight types: integer, double, Boolean, NULL, string, array, object, and resource. Five of 
these are simple types: Integers are whole numbers, doubles are floating-point numbers, Booleans 
are true-or-false values, NULL has just one value (N U L L), and strings are sequences of characters. 
Arrays are a compound type that holds other PHP values, indexed either by integers or by strings. 
Objects are instances of programmer-defined classes, which can contain both member variables and 
member functions, and which can inherit functions and data types from other classes. (We address 
arrays in Chapter 8 and objects in Chapter 20.) Finally, resources are special references to memory 
allocated from external programs, which memory PHP frees automatically when they are no longer 
needed (we cover resources in Chapter 25). 

Only values are typed in PHP — variables have no inherent type other than the value of their most 
recent assignment. PHP automatically converts value types as demanded by the context in which the 
value is used. The programmer can also explicitly control types by means of both conversion func- 
tions and type casts. 

PHP code is whitespace insensitive, and although variable names are case sensitive, basic language 
constructs and function names are not. Simple PHP expressions are combined into larger expres- 
sions by operators and function calls, and statements are expressions with a terminating semicolon. 
Variables are denoted by a leading $ character and are assigned using the = operator. They need 
no type declarations and have reasonable default values if used before they are assigned. Variable 
scope is global except inside the body of functions, where it is local to the function unless explicitly 
declared otherwise. 

The simplest way to send output to the user is by using either echo or print, which output the 
string arguments. They are particularly useful in combination with doubly quoted strings, which 
automatically replace embedded variables with their values. 
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It's difficult to write interesting programs if you can't make the course of 
program execution depend on anything. In a weak sense, the behavior 
of code that prints variables depends on the variable values, but that 
is as exciting as filling out a template. As programmers, we want programs 
that react to something (the world, the time of day, user input, or the con- 
tents of a database) by doing something different. 

This kind of program reaction requires a control structure, which indicates 
how different situations should lead to the execution of different code. 
In Chapter 4, we informally used the i f control structure without really 
explaining it; in this chapter, we lay out every kind of control structure 
offered by PHP and study their workings in detail. 



NOTE 



Experienced C programmers: Of all the features in PHP, control 
is probably the most reliably C-like — all the structures you are 
used to are here, and they work the same way. 



The two broad types of control structures we will talk about are branches 
and loops. A branch is a fork in the road for a program's execution — 
depending on some test or other, the program goes either left or right, 
possibly following a different path for the rest of the program's execution. 
A loop is a special kind of branch, where one of the execution paths jumps 
back to the beginning of the branch, repeating the test and possibly the 
body of the loop. 

Before we can make interesting use of control structures, however, we have 
to be able to construct interesting tests. We'll start from the very simplest 
of tests, working our way up from the constants TRUE and FALSE and then 
move on to using these tests in more complicated code. 



IN THIS CHAPTER 



Boolean expressions 



Branching 



Looping 



Terminating execution 



Exceptions 



Using functions 



Function documentation 



Defining your own functions 
Functions and variable scope 
Function scope 
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Any real programming language has some kind of capability for procedural abstraction — a way to 
name pieces of code so that you can use them as building blocks in writing other pieces of code. 
Some scripting languages lack this capability, and we can tell you from our own sorrowful experi- 
ence that complex server-side code can quickly become unmanageable without it. 

PHP's mechanism for this kind of abstraction is the function. There are really two kinds of functions 
in PHP — those that have been built into the language by the PHP developers and those defined by 
individual PHP programmers. 

In this chapter, we also look at how to use the large body of functions already provided in PHP and 
then, a bit later, how to define your own functions. Luckily, there is no real difference between using 
a built-in function and using your own functions. But first, let's discuss control. 



Boolean Expressions 

Every control structure in this chapter has two distinct parts: the test (which determines which part 
of the rest of the structure executes), and the dependent code itself (whether separate branches or the 
body of a loop). Tests work by evaluating a Boolean expression, an expression with a result treated as 
either true or false. 



Boolean constants 

The simplest kind of expression is a simple value, and the simplest Boolean values are the con- 
stants TRUE and FALSE. We can use these constants anywhere we would use a more complicated 
Boolean expression, and vice versa. For example, we can embed them in the test part of an i f -el se 
statement: 

if (TRUE) 

print("This will always pri nt<ESR>" ) ; 
else 

print ("This will never print<BR>"); 
Or equivalently: 

if (FALSE) 

print ("This will never print<BR>"); 
else 

print("This will always print<BR>"); 



Logical operators 

Logical operators combine other logical (aka Boolean) values to produce new Boolean values. The 
standard logical operations (and, or, not, and exclusive-or)are supported by PHP, which has 
alternate versions of the first two, as shown in Table 5-1. 
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TABLE 5-1 



Logical Operators 


Operator 


Behavior 


and 


Is true if and only if both of its arguments are true. 


or 


Is true if either (or both) of its arguments are true. 


! Is true if its single argument (to the right) is false and false if its argument is true. 


xor 


Is true if either (but not both) of its arguments are true. 


&& 


Same as and but binds to its arguments more tightly. (See the discussion of precedence later 




in the chapter.) 


Same as or but binds to its arguments more tightly. 



The && and | | operators will be familiar to C programmers. The ! operator is usually called not, 
since it negates the argument it operates on. 

As an example of using logical operators, consider the following expression: 

( ( $statement_l && $statement_2 ) || 
( $statement_l && ! $statement_2 ) jj 
( ! $statement_l && $statement„2) j 
( ! $statement_l && ! $statement_2 ) ) 

This is a tautology, meaning that it is always true regardless of the values of the statement variables. 
There are four possible combinations of truth values for the two variables, each of which is repre- 
sented by one of the && expressions. One of these four must be true, and because they are linked by 
the | | operator, the entire expression must be true. 

Here's another, slightly trickier tautology using xor: 

( ( $statement_l and $statement„2 and 
$statement_3 ) xor 

( ( ! ( $statement_l and $statement_2 ) ) or 
( ! ( $statement_l and $statement_3 ) ) or 
( ! ( $statement_2 and $statement_3 ) ) ) ) 

In English, this expression says, "Given three statements, one and only one of the following two things 
hold — either 1) all three statements are true, or 2) there are two statements that are not both true." 

Precedence of logical operators 

Just as with any operators, some logical operators have higher precedence than others, although pre- 
cedence can always be overridden by grouping subexpressions using parentheses. The logical opera- 
tors listed in declining order of precedence are: ! , &&, | | , and, xor, or. Actually, and, xor, and or 
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have much lower precedence than the others, so that the assignment operator (=) binds more tightly 
than and but less tightly than &&. 

C '-- p*~.'-' I A complete table of operator precedence and associativity can be found in the online 

manualatwww.php.net. 

Logical operators short-circuit 

One very handy feature of Boolean operators is that they associate left to right, and they short-circuit, 
meaning that they do not even evaluate their second argument if their truth value is unambiguous 
from their first argument. For example, imagine that you wanted to determine a very approximate 
ratio of two numbers but also wanted to avoid a possible division-by-zero error. You can first test to 
make sure that the denominator is not zero by using the ! = (not-equal-to) operator: 

if ($denom != 0 && $numer / $denom > 2) 
print("More than twice as much!"); 

In the case where Sdenom is zero, the && operator should return false regardless of whether the sec- 
ond expression is true or false. Because of short-circuiting, the second expression is not evaluated, 
so an error is avoided. In the case where $denom is not zero, the && operator does not have enough 
information to reach a conclusion about its truth value, so the second expression is evaluated. 

So far, all we've formally covered are the TRUE and FALSE constants and how to combine them to 
make other true-or-false values. Now we'll move on to operators that actually let you make meaning- 
ful Boolean tests. 

Comparison operators 

Table 5-2 shows the comparison operators, which can be used for either numbers or strings 
(although you should see the cautionary sidebar entitled "Comparing Things That Are Not Integers"). 



TABLE 5-2 



Comparison Operators 


Operator 


Name 


Behavior 




Equal 


True if its arguments are equal to each other, false otherwise 


i = 


Not equal 


False if its arguments are equal to each other, true otherwise 


< 


Less than 


True if the left-hand argument is less than its right-hand 
argument but false otherwise 


> 


Greater than 


True if the left-hand argument is greater than its right-hand 
argument but false otherwise 


<= 


Less than or equal to 


True if the left-hand argument is less than its right-hand 
argument or equal to it but false otherwise 
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Operator 


Name 


Behavior 


>= 


Greater than or equal to 


True if the left-hand argument is greater than its right-hand 
argument or equal to it but false otherwise 




Identical 


True if its arguments are equal to each other and of the same 
type but false otherwise 



As an example, here are some variable assignments, followed by a compound test that is always true: 

$three = 3; 

$four = 4; 

$my_pi = 3.14159; 

if (($three == $three) and 

($four === $four) and 

($three != $four) and 

($three < $four) and 

($three <= $four) and 

($four >= $three) and 

($three <= $three) and 

($my_pi > $three) and 

($my_pi <= $four)) 
print("My faith in mathematics is restored ! <BR> ") ; 
else 

print("Sure you typed that ri ght?<BR> " ) ; 



CAUTION 



Watch out for a very common mistake: confusing the assignment operator (=) with the 
comparison operator (==). The statement i f ( $three = $four) will (probably unex- 
pectedly) set the variable $th ree to be the same as $f our; what's more, the test will be true if $ four 
is a true value! 



Operator precedence 

Although overreliance on precedence rules can be confusing for the person who reads your code 
next, it's useful to note that comparison operators have higher precedence than Boolean operators. 
This means that a test like the following: 

if ($small_num > 2 && $small_num < 5) ... 



doesn't need any parentheses other than those shown. 



String comparison 

The comparison operators may be used to compare strings as well as numbers (see the cautionary 
sidebar). We would expect the following code to print its associated sentence (with apologies to Billy 
Bragg): 

if (("Marx" < "Mary") and 
("Mary" < "Marzipan")) 
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{ 

pri nt (" Between Marx and Marzipan in the "); 
pri nt( "di cti onary , there was Mary.<BR>"); 

} 

The comparisons are case sensitive, and the only reason that this example will print anything is 
because our values are case-consistent. Because of the capitalization of D e n n i s , the following will 
not print anything: 

if (("deep blue sea" < "Dennis") and 
( "Denni s" < "devi 1 " ) ) 

{ 

pri nt (" Between the deep blue sea and "); 
print("the devil, that was me.<BR>"); 

} 



Comparing Things That Are Not Integers 

y^lthough comparison operators work with numbers or strings, a couple of gotchas lurk here. 

First of all, although it is always safe to do less-than or greater-than comparisons on doubles (or even 
between doubles and integers), it can be dangerous to rely on equality comparisons on doubles, especially 
if they are the result of a numerical computation. The problem is that a rounding error may make two values 
that are theoretically equal differ slightly. 

Second, although comparison operators work for strings as well as numbers, PHP's automatic type conversions 
can lead to counterintuitive results when the strings are interpretable as numbers. For example, the code: 

$string_l = "00008" ; 
$string_2 = "007"; 
$string_3 = "00008-0K" ; 
if ( $ s t r i n g_2 < $ s t r i n g_l ) 
p r i n t ( " $ s t r i n g_2 is less 
if ($string_3 < $string_2) 
p r i n t ( " $ s t r i n g_3 is less 
if ($string_l < $string„3) 



than 
than 



$string_KBR>" ) ; 
$string_2<BR>" ) ; 



pr i nt ( " $st ri ng_l is less than $stri ng_3<BR> 



1 ess 

gives this output (with comments added): 

007 is less than 00008 // numerical comparison 
00008-OK is less than 007 // string comparison 

00008 is less than 00008-OK // string comp. - contradiction! 

When it can, PHP will convert string arguments to numbers, and when both sides can be treated that way, the 
comparison ends up being numerical, not alphabetic. The PHP designers view this as a feature, not a bug. Our 
view is that if you are comparing strings that have any chance of being interpreted as numbers, you're better 
off using the st rcmp ( ) function. 
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The ternary operator 

One especially useful construct is the ternary conditional operator, which plays a role somewhere 
between a Boolean operator and a true branching construct. Its job is to take three expressions and 
use the truth value of the first expression to decide which of the other two expressions to evaluate 
and return. The syntax looks like: 

testExpressi on ? yesExpressi on : noExpression 

The value of this expression is the result of yes - express ion if test -express ion is true; other- 
wise, it is the same as no-expressi on. 

For example, the following expression assigns to $max_num either $f i rst_num or $second_num, 
whichever is larger: 

$max_num = $first_num > $second_num ? $first_num : SseconcLnum ; 
As you will see, this is equivalent to: 

if ($first_num > $second_num) 

$max_num = $f i rst_num ; 
else 

$max_num = $second_num; 
but is somewhat more concise. 



Branching 

The two main structures for branching are i f and switch. I f is a workhorse and is usually the first 
conditional structure anyone learns. Swi ten is a useful alternative for certain situations where you 
want multiple possible branches based on a single value and where a series of i f statements would 
be cumbersome. 

If-else 

The syntax for i f is: 

if (test) 

statement - 1 

Or with an optional else branch: 

if [test) 

statement-1 
else 

statement-2 
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When an i f statement is processed, the test expression is evaluated, and the result is interpreted 
as a Boolean value. If test is true, statement- 1 is executed. If test is not true, and there is an 
else clause, statement -2 is executed. If test is false, and there is no else clause, execution sim- 
ply proceeds with the next statement after the i f construct. 

Note that a statement in this syntax can be a single statement that ends with a semicolon, a brace- 
enclosed block of statements, or another conditional construct (which itself counts as a single state- 
ment). Conditionals can be nested inside each other to arbitrary depth. Also, the Boolean expression 
can be a genuine Boolean (TRUE, FALSE, or the result of a Boolean operator or function), or it can be 
a value of another type interpreted as a Boolean. 



f-rj fS"£j£j _7[> pj: For the full story on how values of non-Boolean types are treated as Booleans, see 
~' J ~ "^"^ J Chapter 25. The short version is that the number 0, the string " 0 ", and the empty string, 

" ", are false, and almost every other value is true. 

The following example, which prints a statement about the absolute difference between two num- 
bers, shows both the nesting of conditionals and the interpretation of the test as a Boolean: 

if ($first - $second) 
if (Ifirst > Ssecond) 
{ 

$difference = $first - $second; 

print("The difference is $di fference<BR>" ) ; 

) 

else 
{ 

Idifference = $second - $first; 

printC'The difference is $di fference<BR>" ) ; 

} 

else 

print("There is no di fference<BR>" ) ; 

This code relies on the fact that the number 0 is interpreted as a false value — if the difference is 
zero, then the test fails, and the no difference message is printed. If there is a difference, a fur- 
ther test is performed. (This example is artificial, because a test like $f i rst != $second would 
accomplish the same thing comprehensibly.) 



Else attachment 

At this point, former Pascal programmers may be warily wondering about else attachment — that 
is, how does an el se clause know which i f it belongs to? The rules are simple and are the same as 
in most languages other than Pascal. Each el se is matched with the nearest unmatched i f that can 
be found, while respecting the boundaries of braces. If you want to make sure that an i f statement 
stays solo and does not get matched to an el se, wrap it up in braces like this: 

if ($num % 2 == 0) // $num is even? 
{ 

if ($num > 2) 
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print("num is not prime<BR>" ) ; 

} 

else 

print("num is odd<BR>"); 

This code will print num is not prime if $num happens to be an even number greater than 2 , n u m 
i s odd if $num is odd, and nothing if $num happens to be 2. If we had omitted the curly braces, the 
el se would attach to the inner i f , and so the code would buggily print num i s odd if $num were 
equal to 2 and would print nothing if $ num were actually odd. 



In this chapter's examples, we often use the modulus operator (%), which is explained in 
Chapter 9. For the purposes of these examples, all you need to know is that if $ x % $y is 
zero, $x is evenly divisible by $y. 



Elseif 

It's very common to want to do a cascading sequence of tests, as in the following nested i f statements: 

if ($day == 5) 

print ("Five golden rings<BR>"); 
else 

if ($day == 4) 

print("Four calling birds<BR>"); 
else 

if ($day == 3) 

print("Three French hens<BR>"); 
else 

if ($day == 2) 

print("Two turtl edoves<BR>" ) ; 
else 

if ($day == 1) 

print("A partridge in a pear tree<BR>"); 



We have indented this code to show the real syntactic structure of inclusions — although 
this is always a good idea, you will often see code that does not bother with this and 
where each else line starts in the first column. 



This pattern is common enough that there is a special elseif construct to handle it. We can rewrite 
the preceding example as: 

if ($day == 5) 

print ("Five golden rings<BR>"); 
elseif ($day == 4) 

print("Four calling birds<BR>"); 
el seif ($day == 3) 

print("Three French hens<BR>"); 
elseif ($day == 2) 

print("Two turtl edoves<BR>" ) ; 
elseif ($day == 1) 

print("A partridge in a pear tree<BR>"); 
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Branching and HTML Mode 



As you may have learned from earlier chapters, you should feel free to use the PHP tags to switch back and 
forth between HTML mode and PHP mode, whenever it seems convenient. If you need to include a large 
chunk of HTML in your page that has no dynamic code or interpolated variables, it can be simpler and more 
efficient to escape back into HTML mode and include it literally than to send it using pri nt or echo. 

What may not be as obvious is that this strategy works even inside conditional structures. That is, you can 
use PHP to decide what HTML to send and then "send" that HTML by temporarily escaping back to HTML 
mode. 

For example, the following cumbersome code uses print statements to construct a complete HTML page 
based on the supposed gender of the viewer. (We're assuming a nonexistent Boolean function called f emal e ( ) 
that tests for this.) 

<HTMLXHEAD> 
<?php 

if (catO) 
1 

print("<TITLE>The cat-only site</TITLEXBR>") ; 
print("</HEADXBODY>") ; 

print("This site has been specially constructed "); 
print("for cats only.<BR> No dogs allowed here!"); 

1 

else 



print("<TITLE>The dog-only site</TITLEXBR>") ; 
print("</HEADXBODY>") ; 

print("This site has been specially constructed 
print("for dogs only.<BR> No cats allowed here!' 



) ; 



?> 



</BODYX/HTML> 

Instead of all these print statements, we can duck back into HTML mode within each of the two branches: 

<HTMLXHEAD> 
<?php 

if (catO) 
1 

<TITLE>The cat-only site</TITLE> 
</HEADXBODY> 

This site has been specially constructed 
for cats only.<BR> No dogs allowed here! 
<?php 
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) 

else 
{ 

?> 

<TITLE>The dog-only si te</TITLEXBR> 
</HEADXBODY> 

This site has been specially constructed 
for dogs only.<BR> No cats allowed here! 
<?php 
} 

?> 

</B00YX/HTML> 

This version is somewhat more difficult to read, but the only difference is that it replaces each set of pri nt 
statements with a block of literal HTML that starts with a closing PHP tag (?>) and ends with a starting PHP 

tag ( <?php). 

In this book's examples, we mostly avoid this kind of conditional inclusion, simply because we feel that it 
may be harder for the novice PHP programmer to decipher. But that shouldn't stop you — literal inclusion 
has advantages, including fast execution. (In HTML mode, all the PHP engine must do is pass on characters 
and watch for the next PHP start tag, which is inevitably faster than parsing and executing print statements, 
especially if they include doubly quoted strings.) 

A third alternative, when large blocks of HTML are conditionally included, is the heredoc, alluded to in Chapter 
4 and explained fully in Chapter 7. The heredoc will allow you to include large blocks of HTML code inside a 
chunk of PHP without several consecutive print statements. 



The if, el sei f construct allows for a sequence of tests that executes only the first branch that has a 
successful test. In theory, this is syntactically different from the previous example (we have a single 
construct with five branches rather than a nesting of five two-branch constructs), but the behavior is 
identical. Use whichever syntax you find more appealing. 

Switch 

For a specific kind of multiway branching, the switch construct can be useful. Rather than branch 
on arbitrary logical expressions, switch takes different paths according to the value of a single 
expression. The syntax is as follows, with the optional parts enclosed in square brackets ([ ]): 

swi tch ( express i on) 
{ 

case value-1: 
statement-1 ; 
statement-2 ; 

[break; ] 
case value-2: 
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statement-3 ; 
statement -4 ; 

[break ; ] 

[def a ill t : 

defaul t- statement ;] 

} 

The expression can be a variable or any other kind of expression, as long as it evaluates to a simple 
value (that is, an integer, a double, or a string). The construct executes by evaluating the expression 
and then testing the result for equality against each case value. As soon as a matching value is found 
subsequent statements are executed in sequence until the special statement (break;) or until the 
end of the switch construct. (As we'll see in the "Looping" section of this chapter, break can also 
be used to break out of looping constructs.) A special defaul t tag can be used at the end, which 
will match the expression if no other case has matched it so far. 

For example, we can rewrite the i f -el se example as follows: 

swi tch ( $day ) 

{ 

case 5: 
p ri n t ( 
brea k ; 
case 4: 
p r i n t ( 
brea k ; 
case 3: 
p r i n t ( 
brea k ; 
case 2: 
p r i n t ( 
brea k ; 
defaul t : 
p r i n t ( 

} 

This will print a single appropriate line for days 2-5; for any day other than those, it will print A 
partridge in a pear tree. Although switch will accept only a single argument, there's no rea- 
son why that argument can't be the value of expressions evaluated previously in your code. 

[ r- 1 ' 1 - "j"^"' jxj '■ ' The single most confusing aspect of swi tch is that all cases after a matching case will 
* ^ r -^ - execute, unless there are brea k statements to stop the execution. In the "partridge" 

example, the break statements ensure that we see only one line from the song at a time. If we remove 
the break statements, we will see a sequence of lines counting down to the final line, just as in the 
song. 



'Five golden rings<BR>"); 



'Four calling birds<BR>") 



'Three French hens<BR>"l 



'Two turtl edoves<BR>' 



'A partridge in a pear tree<BR>") 
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Looping 

Congratulations! You just passed the boundary from scripting into real programming. The branch- 
ing structures we have looked at so far are useful, but there are limits to what can be computed with 
them alone. On the other hand, it's well established in theoretical computer science that any lan- 
guage with tests plus unbounded looping can do pretty much anything that any other language can 
do. You may not actually want to write a C compiler in PHP, for example, but it's nice to know that 
no inherent language limits are going to stop you. 

Bounded loops versus unbounded loops 

A bounded loop executes a fixed number of times — you can tell by looking at the code how many 
times the loop will iterate, and the language guarantees that it won't loop more times than that. An 
unbounded loop repeats until some condition becomes true (or false), and that condition is dependent 
on the action of the code within the loop. Bounded loops are predictable, whereas unbounded loops 
can be as tricky as you like. 

Unlike some languages, PHP doesn't actually have any constructs specifically for bounded loops — 
while, do-while, and for are all unbounded constructs — but as you will see in this section, an 
unbounded loop can do anything a bounded loop can do. 

i ^J^-OS^'^i^ ^.F '° ac ' c '' t ' on to tne !°°P' n g constructs in this chapter, PHP provides functions for iterating 
' -" over the contents of arrays, which are covered in Chapter 8. 

While 

The simplest PHP looping construct is wh i 1 e, which has the following syntax: 

while {condition) 
statement 

The while loop evaluates the condition expression as a Boolean — if it is true, it executes statement 
and then starts again by evaluating condition. If the condition is false, the while loop terminates. Of 
course, just as with i f , statement may be a single statement or it may be a brace-enclosed block. The 
body of a wh i 1 e loop may not execute even once, as in: 

while (FALSE) 

print("This will never print. <BR>"); 

Or it may execute forever, as in this code snippet: 

while (TRUE) 

print("All work and no play makes 
Jack a dul 1 boy .<BR>" ) ; 
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Or it may execute a predictable number of times, as in: 

Scount = 1; 
while (Scount <= 10) 
t 

print("count is $count<BR> " ) ; 
$count = $count + 1 ; 

1 

which will print exactly 10 lines. (For more interesting examples, see the "Looping examples" sec- 
tion, later in this chapter.) 

Do-while 

The d o - w h i 1 e construct is similar to w h i 1 e , except that the test happens at the end of the loop. 
The syntax is: 

do statement 

while ( express i on) ; 

The statement is executed once, and then the expression is evaluated. If the expression is true, the 
statement is repeated until the expression becomes false. The only practical difference between 
whi 1 e and do-whi 1 e is that the latter will always execute its statement at least once. For example: 

Scount = 45; 
do 

t 

print("count is $count<BR>" ) ; 
Scount = Scount + 1 ; 

1 

while (Scount <= 10) ; 
prints the single line: 
count is 45 

For 

The most complicated looping construct is f on, which has the following syntax: 

fon { i ni ti al -express! on; 
termi nati on-check; 
1 oop- end -expressi on) 
statement 

In executing a fon statement, first the initial- expression is evaluated just once, usually to initialize 
variables. Then termination-check is evaluated — if it is false, the for statement concludes, and if it is 
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true, the statement executes. Finally, the loop- end- expression is executed and the cycle begins again 
with termination- check. As always, by statement we mean a single (semicolon-terminated) statement, a 
brace- enclosed block, or a conditional construct. 

If we rewrote the preceding for loop as a whi 1 e loop, it would look like this: 

initial -expressi on ; 
while (termination-check) 
{ 

statement 

loop-end-expression; 

} 

Actually, although the typical use of for has exactly one initial-expression, one termination-check, 
and one loop-end-expression, it is legal to omit any of them. The termination-check is taken to be 
always true if omitted, so: 

for ( ; ; ) 

statement 

is equivalent to: 

while (TRUE) 
statement 

It is also legal to include more than one of each kind of for clause, separated by commas. The 
termination-check will be considered to be true if any of its subclauses is true; it is like an 'or' test. 
For example, the following statement: 

for ($x = 1 , $y = 1, $z = 1; //initial expressions 
$y < 10, $z < 10; // termination checks 

$x = $x + 1, $y = $y + 2, // loop-end expressions 
$z = $z + 3) 
print("$x, $y, $z<BR>"); 

would give the browser output: 

1, 1, 1 

2, 3, 4 

3, 5, 7 

Although the for syntax is the most complex of the looping constructs, it is often used for simple 
bounded loops, using the following idiom: 

for ($count = 0; $count < $limit; $count = Icount + 1) 
statement 
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Looping examples 

Now let's look at some examples. 

A bounded for loop 

Listing 5-1 shows a typical use of bounded for loops. The page produced by Listing 5-1 is shown in 
Figure 5-1. 



LISTING 5-1 



A division table 

<?php 

$start_num = 1 ; 
$end_num = 10; 

?> 

<HTML> 
<HEAD> 

<TITLE>A division tabl e</TITLE> 

</HEAD> 

<B0DY> 

<H2>A division table</H2> 

<TABLE B0RDER=1> 

<?php 

print("<TR>") ; 
print("<TH> </TH>"); 
for ($count_l = $start_num; 
$count_l <= $end_num; 
$count_l++) 
print( "<TH>$count_K/TH>" ) ; 
print("</TR>") ; 

for ($count_l = $start_num; 
$count_l <= $end_num; 
$count_l++) 

{ 

print ("<TRXTH>$count_K/TH>" ) ; 
for ($count_2 = $start_num; 

$count_2 <= $end_num; 

$count_2++) 

{ 

$result = $count_l / $count„2; 
printf("<TD>°/;.3f</TD>", 

$result); // see Chapter 7 

} 

print("</TR>\n"); 
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?> 

</TABLE> 

</B0DY> 

</HTML> 



FIGURE 5-1 
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-at, ^JJ F3 \& I 



The main body of this code simply has one for loop nested inside another, with each loop executing 
10 times, resulting in a 10 x 10 table. Each iteration of the outer loop prints a row, whereas each inner 
iteration prints a cell. The only novel feature is the way we chose to print the numbers — we used 
pri ntf (covered in Chapter 7), which allows us to control the number of decimal places printed. 

p .- r- '■ ' The $ v a r i a b 1 e _name++ feature used above is called an increment. It's a fairly standard 
"■o^^" shorthand for $vari abl e_name + 1. 

An unbounded while loop 

Now let's look at a loop not so obviously bounded. The sole purpose of the code in Listing 5-2 is to 
approximate the square root of 81 (using Newton's method). The approximation starts with a guess 
of 1 and then "zeros in" on the actual square root of 9 by improving the guesses. A trace of this 
approximation is shown in Figure 5-2. 
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LISTING 5-2 



Approximating a square root 

<HTML> 
<HEAD> 

<TITLE>Approxi mati ng a square root</TITLE> 

</HEAD> 

<B0DY> 

<H3>Approximati ng a square root</H3> 
<?php 

$target = 81 ; 
$guess = 1.0; 
$precision = 0.0000001; 

$guess_squared = $guess * $guess; 
while ( ( $guess_squared - $target > $precision) or 
( $guess_squared - $target < - $precision)) 

{ 

print( "Current guess: $guess is the square 

root of $target<BR>" ) ; 
$guess = ($guess + ($target / $guess)) / 2; 
$guess_squared = $guess * $guess; 

} 

pri nt ( " $guess squared = $guess_squared<BR>" ) ; 
?> 

</B0DY> 
</HTML> 



Now, although it nicely illustrates a potentially unbounded loop, this approximation example is very 
artificial — first, because PHP already has a perfectly good square-root function (sqrt) and second, 
because the number 81 is hardcoded into the page. We can't use this page to find the square root of 
any other number. 

Break and continue 

The standard way to get out of a looping structure is for the main test condition to become false. The 
special commands break and conti nue offer an optional side exit from all the looping constructs, 
including whi 1 e, do-whi 1 e, and for: 

■ The break command exits the innermost loop construct that contains it. 

■ The continue command skips to the end of the current iteration of the innermost loop 
that contains it. 
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FIGURE 5-2 



Approximating a square root 
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Approximating a square root 






Current guess: 1 is the square root of 81 
Current guess: 41 is the squar e r oot of 81 
Current guess: 21.487804S7S049 is tlie square r oot of 81 
Current guess: 12.6286924f>0375 rs the square root of 81 
Cirrrentgrress: 9. 52 13 29066772 is tire square r oot of 81 
Current guess: 9.0142723769946 is tire square root of 81 
Current guess: 9.0000112987902 is tire square root of 81 
9.0000000000071 squared = 81.000000000128 
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For example, the following code: 

for ($x = 1; $x < 10; $x++) 
{ 

// if $x is odd, break out 
if ($x % 2 != 0) 

break ; 
p r i n t ( " $ x " ) ; 

} 

prints nothing, because 1 is odd, which terminates the for loop immediately. On the other hand, 
the code: 

for ($x = 1; $x < 10; $x++) 
{ 

// if $x is odd, skip this loop 
if ($x % 2 != 0) 

continue; 
p r i n t ( " $ x " ) ; 
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prints: 

2 4 6 8 

because the effect of the continue statement is to skip the printing of any odd numbers. 

Using the break command, the programmer can choose to dispense with the main termination test 
altogether. Consider the following code, which prints a list of prime numbers (that is, numbers not 
divisible by something other than 1 or the number itself): 

$1 i mi t = 500; 
$to_test = 2; 
while(TRUE) 
{ 

$testdiv = 2; 

if ($to_test > $ 1 i m i t ) 

break ; 
while (TRUE) 

{ 

if ($testdiv > sqrt ( $to_test ) ) 
f 

print " $ t o_t est " ; 
brea k ; 

) 

// test if $to_test is divisible by $testdiv 
if ($to_test % $testdiv == 0) 
break ; 

$testdi v = Stestdi v + 1 ; 

} 

$to_test = $to_test + 1; 

} 

In the preceding code, we have two while loops — the outer loop works through all the numbers 
between 1 and 500, and the inner loop actually does the testing with each possible divisor. If the 
inner loop finds a divisor, the number is not prime, so it breaks out without printing anything. If, on 
the other hand, the testing gets as high as the square root of the number, we can safely assume that 
the number must be prime, and the inner loop is broken without printing. Finally, the outer loop is 
broken when we have reached the limit of numbers to test. The result in this case is a list of primes 
less than 500: 

2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 
89 97 101 103 107 109 113 127 131 137 139 149 151 157 163 167 
173 179 181 191 193 197 199 211 223 227 229 233 239 241 251 257 
263 269 271 277 281 283 293 307 311 313 317 331 337 347 349 353 
359 367 373 379 383 389 397 401 409 419 421 431 433 439 443 449 
457 461 463 467 479 487 491 499 

Notice that it is crucial to this code that break interrupt the inner w h i 1 e loop only. 
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I p rj £j '£J£j"_, pjj There is another iteration construct, called f oreach, which is used only for iterating 
* w " • ' over arrays. We cover it in Chapter 8. 

A note on infinite loops 

If you've ever programmed in another language, you've probably had the experience of acciden- 
tally creating an infinite loop (a looping construct whose exit test never becomes true and so never 
returns). The first thing to do when you realize this has happened is to interrupt the program, which 
will otherwise continue "forever" and use up a lot of CPU time. But what does it mean to interrupt a 
PHP script? Is it sufficient to click the Stop button on your browser? 

As it turns out, the answer is dependent on some PHP configuration settings — you can set the PHP 
engine to ignore interruptions from the browser (like the result of clicking Stop) and also to impose 
a time limit on script execution (so that "forever" will only be a short time). The default configura- 
tion for PHP is to ignore interruptions, but with a script time limit of 30 seconds — the time limita- 
tion means that you can afford to forget about infinite loops that you may have started. 

j p rj rj^CjTjy P_p" ^ or more on tne configuration of PHP, see Chapter 29. 

Alternate Control Syntaxes 

PHP offers another way to start and end the bodies of the if, switch, for, and whi 1 e constructs. 
It amounts to replacing the initial brace of the enclosed block with a colon and the closing brace 
with a special ending statement for that construct (endi f , endswi tch, endf or, or endwhi 1 e). For 
example, the i f syntax becomes: 

i f ( express i on) : 
statementl 
statement2 

e n d i f ; 

Or: 

i f ( express i on) : 
statementl 
statement2 

el seif (expressi on2) : 
statement3 

else: 

statement4 

endi f ; 
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Note that the el se and el sei f bodies also begin with colons. The corresponding whi 1 e syntax is: 

whi 1 e ( expressi on) : 

statement 
endwhi 1 e ; 

Which syntax you use is a matter of taste. The nonstandard syntax in PHP is largely used for histori- 
cal reasons and for the comfort of people who are familiar with it from the early versions of PHP. We 
will consistently use the standard syntax in the rest of this book. 



Terminating Execution 

Sometimes you just have to give up, and PHP offers a construct that helps you do just that. The 
exi t ( ) construct takes either a string or a number as argument, prints out the argument, and 
then terminates execution of the script. Everything that PHP produces up to the point of invoking 
exi t ( ) is sent to the client browser as usual, and nothing in your script after that point will even be 
parsed — execution of the script stops immediately. If the argument given to exit is a number rather 
than a string, the number will be the return value for the script's execution. Because exit is a con- 
struct, not a function, it's also legal to give no argument and omit the parentheses. 

The d i e ( ) construct is an alias for e x i t ( ) and so behaves exactly the same way. (We'll usually use the 
d i e ( ) version because we find the name more evocative.) So what's the point of ex i t ( ) and diet ) ? 
One possible use is to cut off production of a web page when your script has determined that there is no 
more interesting information to send, without bothering to wrap up the different branches in a condi- 
tional construct. This usage can make long scripts somewhat difficult to read and debug, however. 

A better use for d i e ( ) is to make your crashes informative. It's good to get into the habit of test- 
ing for unexpected conditions that would crash your script if they were true, and throw in a d i e ( ) 
statement with an informative message. If you're correct in your expectations, the d i e ( ) will never 
be invoked; if you're wrong, you will have an error message of your own rather than a possibly 
obscure PHP error. For example, consider the following pseudocode, which assumes that we have 
functions to make a database connection and that we then use that database connection: 

$connection = ma ke_database_connecti on ( ) ; 
if ( ! $connecti on ) 

die("No database connection!"); 
use_database„connecti on($connection) ; 

This example assumes that our imaginary function m a k e_d a t a b a s e_c o n n e c t i o n ( ), like many 
PHP functions, returns a useful value if it succeeds, and a false value if it fails. An even more com- 
pact version of the preceding code takes advantage of the fact that o r has lower precedence than the 
= assignment operator. 

$connection = ma ke_database_connecti on ( ) 

or die("No database connection!"); 
use_database„connecti on($connection) ; 
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This works because the o r operator short-circuits, and therefore the d i e ( ) construct will only be 
evaluated if the expression $ connecti on = ma ke_da tabase_connect i on ( ) has a false value. 
Because the value of an assignment expression is the value assigned, this code ends up being equiva- 
lent to the earlier version. (Note that this would not work the same way if we used | | instead of 
or, because | | has higher precedence than assignment, and so $connection would end up being 
assigned to the true-or-false result of the | | expression.) 




Before PHP5, the control structures we've presented so far were really the only alterna- 
tives; control would flow from the first statement in a file to the last (possibly bounced 



around by function calls), unless prematurely terminated with d i e ( ) . With exception handling, PHP5 
introduces an alternate way to deal with problematic conditions, and one that is much more flexible 
than di e ( ). We treat exceptions briefly later in this chapter, and more thoroughly in Chapter 30. 

In Table 5-3, we summarize all the control structures you've seen thus far. 



TABLE 5-3 



PHP Control Structures 


Name 


Syntax 


Behavior 


If 


if (test)statement-l 


Evaluate test and if it is true, execute 


(or if-else) 


-or- 


statement-! . If test is false and there is an 




if (test) 


else clause, execute statement-2. The 




statement - 1 


el sei f construct is a syntactic shortcut for 




else 


else clauses, where the included statement is 




statement-2 


itself an i f construct. 




-or- 


Statements may be single statements 




if (test) 


terminated with a semicolon or brace- 




statement-1 


enclosed blocks. 




else if (test2) 






statement-2 






else 






statement-3 




Ternary operator 


expression-1 ? 


Evaluate expression-! and interpret it as a 




expression-2 : 


Boolean. If it is true, evaluate expression-2 and 




expressi on-3 


return it as the value of the entire expression. 






Otherwise, evaluate and return expression-3. 



continued 
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TABLE 5-3 



(continued) 



Name 



Syntax 



PHP Control Structures 

Behavior 



If 

(or if-else) 



if (test)statement-l 

-or- 
if (test) 

statement- 1 
else 

statement-2 
-or- 
if (test) 

statement-1 
elseif (test2) 

statement-2 
else 

statement-3 



Evaluate test and if it is true, execute 
statement-! . If test is false and there is an 
else clause, execute statement-2. The 
el sei f construct is a syntactic shortcut for 
else clauses, where the included statement is 
itself an i f construct. 
Statements may be single statements 
terminated with a semicolon or brace- 
enclosed blocks. 



Ternary operator express! on -1 ? 

expression-2 : 
expressi on-3 



Evaluate expression-! and interpret it as a 
Boolean. If it is true, evaluate expression-2 and 
return it as the value of the entire expression. 
Otherwise, evaluate and return expression-3. 



Switch 



swi tch ( expressi on ) 
{ 

case val ue-1 : 
statement-1 
statement-2 

[break; ] 
case val ue-2 : 
statement-3 
statement-4 



Evaluate expression, and compare its value 
to the value in each case clause. When 
a matching case is found, begin executing 
statements in sequence (including those from 
later cases), until the end of the swi tch 
statement or until a break statement is 
encountered. The optional def aul t case 
will execute if no other case has matched the 
expression. 



[break; ] 



[def aul t : 

def aul t-statement] 



While while (condition) Evaluate condition and interpret it as Boolean. 

statement If condition is false, the while construct 

terminates. If it is true, execute statement, and 
keep executing it until condition becomes 
false. Terminate the while loop if the special 
break command is encountered, and skip 
the rest of the current iteration if conti nue is 
encountered. 
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Name 


Syntax 


Behavior 


Do-while 


do statement 


Perform statement once unconditionally, 




u/hilp frnnrli'r'innl' 

Will 1 c ^ UUUU 1 t 1 UII / , 


thpn k"pfin rpnp^tino Qt^fpmpnt iinti cnnriitian 

1 1 1 v_ I 1 IS.CCL' 1 CUCdll 1 1 ti DlClLClllCillL L! Ml II LU/iu/L/U/l 






becomes false. (The break and conti nue 






commands are handled as in whi 1 e.) 


For 


for ( i ni ti al -expressi on ; 

termi na ti on -check ; 

1 oop-end- 
expressi on ) 
statement 


Evaluate initial-expression once 
unconditionally. Then if termination-check 
is true, evaluate statement, and then loop- 
end-expression, and repeat that loop until 
termination-check becomes false. Clauses 



may be omitted, or multiple clauses of the 
same kind can be separated with commas — a 
missing termi nati on-check is treated as 
true. (The break and conti nue commands 
are handled as in whi 1 e.) 



Using Functions 

The basic syntax for using (or calling) a function is: 

functi on_name ( express i on_l , expressi on_2 , .... expressi on_n ) 

This includes the name of the function followed by a parenthesized and comma-separated list of 
input expressions (which are called the arguments to the function). Functions can be called with zero 
or more arguments, depending on their definitions. 

When PHP encounters a function call, it first evaluates each argument expression and then uses 
these values as inputs to the function. After the function executes, the returned value (if any) is the 
result of the entire function expression. 

All the following are valid calls to built-in PHP functions: 

sqrt(9); // square root function, evaluates to 3 
randdO, 10 + 10); // random number between 10 and 20 
strlen("This has 22 characters"); // returns the number 22 
pi ( ) ; // returns the approximate value of pi 

These functions are called with 1, 2, 1, and 0 arguments, respectively. 

Return values versus side effects 

Every function call is a PHP expression, and (just as with other expressions) there are only two rea- 
sons why you might want to include one in your code: for the return value or for the side effects. 
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The return value of a function is the value of the function expression itself. You can do exactly the 
same things with this value as with the results of evaluating any other expression. For example, you 
can assign it to a variable, as in: 

$my_pi = pi ( ) ; 

Or you can embed it in more complicated expressions, as in: 

Sapprox = sqrt( $approx) * sqrt ( $approx ) 

Functions are also used for a wide variety of side effects, including writing to files, manipulating 
databases, and printing things to the browser window. It's okay to make use of both return values 
and side effects at the same time — for example, it is very common to have a side-effecting function 
return a value that indicates whether or not the function succeeded. 

The result of a function may be of any type, and it is common to use the array type as a way for 
functions to return multiple values. 



The architecture of PHP has been cleverly designed to make it easy for other developers to extend. 
The basic PHP language itself is very clean and flexible, but there is not a lot there — most of PHP's 
power resides in the large number of built-in functions. This means that developers can contribute 
simply by adding new built-in functions, which is nice especially because it does not change any- 
thing that PHP users may be relying on. 

Although this book covers many of these built-in functions, explaining some of them in greater 
detail than the online manual can, the manual at www .php.net is the authoritative source for func- 
tion information. In this book, we get to choose our topics to some extent, whereas the PHP docu- 
mentation group has the awesome responsibility of covering every aspect of PHP in the manual. 
Also, although we hope to keep updating this book in future editions, the manual will have the 
freshest information on new additions to the ever-growing PHP functionality. It's worth looking at 
some of the different resources that the PHP site and manual offer. 



To find the manual, head to www . php . net. A handy search bar at the top offers quick and easy 
access to any individual part of the online documentation. Alternatively, find the Documentation 
item at the top of the page. The Documentation page that this tab leads to has links to manual infor- 
mation in a wide variety of formats and languages. 

The largest section of the manual is the function reference, where each built-in function gets its own 
page of documentation. Typically, each group of functions has a page of general explanation, leading 
to pages for individual functions. Each function page starts off with the name of the function and a 
one-line description. This is followed by a C-style header declaration of the function (explained in 



Function Documentation 




Although the following information is correct at this writing, some details may become 
dated or inapplicable if the online manual is reorganized. 
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the next section), followed by a slightly longer description and possibly an example or two, and then 
(in the annotated manual) clarifications and gotcha reports from users. 

Headers in documentation 

For those unfamiliar with C function headers, the very beginning of a function documentation page 
might be confusing. The format is: 

return-type fundi on -name ( typel argl, type2 arg2, . . .); 

This specifies the type of value the function is expected to return, the name of the function, and the 
number and expected types of its arguments. 

Here is a typical header description: 

string substr(string string, int start[, int length]); 

This says that the function s u b s t r ( ) will return a string and expects to be given a string and two 
integers as its arguments. Actually, the square brackets around length indicate that this argument 
is optional — so s ubstr ( ) should be called either with a string and an int, or a string and two ints. 

Unlike in C, the argument types in these documentary headers are not absolute requirements. If 
you call substr ( ) with a number as its first argument, you will not get an error. Instead, PHP will 
convert the first argument to a string as it begins to execute the function. However, the argument 
types do document the intent of the function's author, and it is a good idea either to use the function 
as documented or to understand the type conversion issues well enough that you are sure the result 
will be what you expect. 

In general, the type names used in function documentation will be those of the basic types or of 
their aliases: integer (or i nt), double (or f 1 oat, real ), Boolean, string, array, object, resource, and 
NULL. In addition, you may see the types void and mi xed. The voi d return type means that the 
function does not return a value at all, whereas the mixed argument type means that the argument 
might be of any type. 

Finding function documentation 

What's the best way to find information about a function in the manual? That is likely to depend on 
what kind of curiosity you have. The most common questions about functions are: 

■ I want to use function X. Now, how does X work again? 

■ I'd really like to do task Y. Is there a function that handles that for me? 

For the first type of curiosity, the full version of the online manual offers an automatic lookup by 
function name. You can simply type http://php.net / fundi on Name and the fundi on Name 
will be searched for automatically. Alternately, the "Search For" box in the upper-right corner of 
the manual pages defaults to a mode where it searches for specific function names and displays the 
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corresponding function page if found. (You can also make other choices, including searching the 
mailing list or the entire online documentation — the latter is a good choice when you don't know 
the name of the function you want, but can guess at words that appear on its manual page.) 

For the second type of curiosity, your best bet is probably to use the hierarchical organization of the 
function reference. For example, the substr function shown in the "Headers in Documentation" 
section is found in the "String Functions" section. You can browse the chapter list of the function 
reference for the best fit for the task you want to do. 



Defining Your Own Functions 

User-defined functions are not a requirement in PHP. You can produce interesting and useful web 
sites simply with the basic language constructs and the large body of built-in functions. If you find 
that your code files are getting longer, harder to understand, and more difficult to manage, however, 
it may be an indication that you should start wrapping some of your code up into functions. 

What is a function? 

A function is a way of wrapping up a chunk of code and giving that chunk a name, so that you can 
use that chunk later in just one line of code. Functions are most useful when you will be using the 
code in more than one place, but they can be helpful even in one-use situations, because they can 
make your code much more readable. 

Function definition syntax 

Function definitions have the following form: 

function function-name ( $argument-l , $argument-2, ..) 

{ 

statement- 1 ■ 
statement-2; 

} 

That is, function definitions have four parts: 

■ The special word functi on 

■ The name that you want to give your function 

■ The function's parameter list — dollar-sign variables separated by commas 

■ The function body — a brace- enclosed set of statements 

Just as with variable names, the name of the function must be made up of letters, numbers, and 
underscores, and it must not start with a number. Unlike variable names, function names are 
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converted to lowercase before they are stored internally by PHP, so a function is the same regardless 
of capitalization. 

The short version of what happens when a user-defined function is called is: 

1 . PHP looks up the function by its name (you will get an error if the function has not yet 
been defined). 

2. PHP substitutes the values of the calling arguments (or the actual parameters) into the vari- 
ables in the definition's parameter list (or the formal parameters). 

3. The statements in the body of the function are executed. If any of the executed statements 
are return statements, the function stops and returns the given value. Otherwise, the 
function completes after the last statement is executed, without returning a value. 



The alert and experienced programmer will have noticed that the preceding description 
implies call-by-value, rather than call-by-reference. In Chapter 26, we explain the differ- 
ence and show how to get call-by-reference behavior. 



Function definition example 



As an example, imagine that we have the following code that helps decide which size of bottled soft 
drink to buy. (This is sometime next year, when supermarket shoppers routinely use their wearable 
wireless web browsers to get to our handy price-comparison site.) 

$liters_l = 1.0 
$price_l =1.59 
$liters_2 = 1.5 
$price_2 =2.09 

$per_liter_l = $price_l / $liters_l; 
$per_liter_2 = $price_2 / $liters_2; 
if ($per_literl < $per_liter2) 

print("The first deal is better ! <BR> ") ; 
else 

print("The second deal is better!<BR>"); 

Because this kind of comparison happens in our web site code all the time, we would like to make 
part of this a reusable function. One way to do this would be the following rewrite: 

function better_deal ($amount_l, $price_l, 

$amount_2, $price_2) 

{ 

$per_amount_l = $price_l / $amount_l; 
$per_amount_2 = $price_2 / $amount_2; 
return ( $per_amount_l < $per_amount_2 ) ; 



$liters_l = 1.0; 
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$price_l = 1.59; 
$1 iters_2 =1.5; 
$price_2 = 2.09; 

if ( better_deal ( $1 i ters_l , $pn'ce_l, 

$liters_2, $price_2)) 

print("The first deal is better ! <BR>" ) ; 

else 

print("The second deal is better ! <BR> ") ; 

Our better_deal function abstracts out the three lines in the previous code that did the arithmetic 
and comparison. It takes four numbers as arguments and returns the value of a Boolean expression. 
As with any Boolean value, we can embed it in the test portion of an i f statement. Although this 
function is longer than the original code, there are two benefits to this rewrite: We can use the func- 
tion in multiple places (saving lines overall), and if we decide to change the calculation, we have to 
make the change in only one place. 

Alternatively, if the only way we ever use these price comparisons is to print which deal is preferred, 
we can include the printing in the function, like this: 

function pri nt_better_deal ($amount_l, $price_l, 

$amount_2, $price_2) 

{ 

$per_amount_l = $price_l / $amount_l; 
$per_amount_2 = $price_2 / $amount_2; 
if ( $per_amount_l < $per_amount_2 ) 

print("The first deal is better ! <BR>" ) ; 
else 

print("The second deal is better ! <BR> ") ; 

} 

$1 iters_l =1.0; 
$price_l = 1.59; 
$1 iters_2 =1.5; 
$price_2 = 2.09; 

pri nt_better_dea 1 ( $1 i ters_l , $ p r i ce_l , 
$liters_2, $price_2); 

Our first function used the return statement to send back a Boolean result, which was used in 
an i f test. The second function has no return statement, because it is used for the side effect of 
printing text to the user's browser. When the last statement of this function is executed, PHP simply 
moves on to executing the next statement after a function call. 

Formal parameters versus actual parameters 

In the preceding examples, the arguments we passed to our functions happened to be variables, but 
this is not a requirement. The actual parameters (that is, the arguments in the function call) may 
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be any expression that evaluates to a value. In our examples, we could have passed numbers to our 
function calls rather than variables, as in: 

print_better_deal (1.0, 1.59, 1.5, 2.09); 

Also, notice that in the examples we had a couple of cases where the actual parameter variable had 
the same name as the formal parameter (for example, $ p r i ce_l), and we also had cases where the 
actual and formal names were different. ($1 i ters_l is not the same as $amount_l.) As we will see 
in the next section, this name agreement doesn't matter either way — the names of a function's for- 
mal parameters are completely independent of the world outside the function, including the function 
call itself. 

Argument number mismatches 

What happens if you call a function with fewer arguments than appear in the definition, or with 
more? As you might have come to expect by now, PHP handles this without anything crashing, but 
it may print a warning depending on your settings for error reporting. 

Too few arguments 

If you supply fewer actual parameters than formal parameters, PHP will treat the unfilled formal 
parameters as if they were unbound variables. However, under the usual settings for error reporting 
in PHP6, you will also see a warning printed to the browser. 

The default error-reporting setting in PHP6 reports on every kind of error except runtime notices, 
which are the least serious condition that is detected. The reason you see warnings about too few 
arguments to a function is that this is treated as a runtime-warning situation (the next most serious 
category). If you really need function calls that sometimes provide too few arguments and seeing 
warnings is unacceptable, you have two options for suppressing the warnings: 

■ You can temporarily change the value of error reporting in your script, with a statement 
like error_reporting( E_ALL A E_N0TICE A E_WARN I NG ;. This will turn off both 
runtime notices and runtime warnings from the point where it appears in your script up 
to the next erro r_ report ing( ) statement (if any). (Note that this is dangerous, as lots of 
other problems might produce warnings besides the one you're interested in.) 

■ You can suppress errors for any single expression by using the error-control operator @, 
which you can put in front of any expression to suppress errors from that expression only. 
For example , if the function call my_function( ) is producing a warning, @my_function( ) 
will not. Note that this is dangerous as well because all types of errors except for parse errors 
will be suppressed. 

We don't advise using either of these workarounds, but we provide them because we are such non- 
judgmental people by nature. PHP actually provides ways to write functions that expect variable 
numbers of arguments (see the "Variable Numbers of Arguments" section in Chapter 26), and using 
them is a much better idea than shooting the messenger. 
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f J P " I Rather than decreasing PHP's reportage of errors, we advise increasing it to the 

maximum level possible when you are developing new code. You can do this glob- 
ally by changing the php . i ni file (see Chapter 29) or simply by including the statement error_ 
report i ng ( E_AL L ) ; at the top of your scripts. Among other things, this increase in reportage will 
mean that you will be warned about variables you have forgotten to assign, which is one of the most 
frequent causes of time-wasting bugs. 

Too many arguments 

If you hand too many arguments to a function, the excess arguments will simply be ignored, even 
when error reporting is set to E„ALL. As you will see in Chapter 26, this tolerance turns out to be 
helpful in defining functions that can take a variable number of arguments. 



Functions and Variable Scope 



As we said in Chapter 4, outside of functions, the rules about variable scope are simple: Assign a 
variable anywhere in the execution of a PHP code file, and the value will be there for you later in 
that file's execution. The rules become somewhat more complicated in the bodies of function defini- 
tions, but not much. 

The basic principle governing variables in function bodies is: Each function is its own little world. 
That is, barring some special declarations, the meaning of a variable name inside a function has 
nothing to do with the meaning of that name elsewhere. (This is a feature, not a bug — you want 
functions to be reusable in different contexts, and so having the behavior be independent of the con- 
text is a good thing. If not for this kind of scoping, you would waste a lot of time chasing down bugs 
caused by using the same variable name in different parts of your code.) 

" k iT iT ^ ' ' f ^ s °^ ' > ^" > * nere ' s a smaM se t of global variables that are automatically visible from 
^^^■■■^•m^^^™! within function definitions, in contradiction to the previous paragraph and the following 
one. These are the superglobal arrays ($_P0ST, $„GET, $__SESS ION, and so on), which contain keys 
and values corresponding to variable bindings from different sources. For more on these variables and 
their uses, see Chapter 6. 

The only variable values that a function has access to are the formal parameter variables (which have 
the values copied from the actual parameters), plus any variables assigned inside the function. This 
means that you can use local variables inside a function without worrying about their effects on the 
outside world. For example, consider this function and its subsequent use: 

function SayMyABCs ( ) 
{ 

$count = 0; 
while ($count < 10) 
{ 

print(chr(ord('A') + $count)); 
Icount = Scount + 1; 
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pri nt ( " <BR>Now I know Icount 1 etters<BR>" ) ; 

} 

$count = 0; 

SayMyABCs( ) ; 

$count = $count + 1; 

print("Now I've made $count function cal 1 ( s ) . <BR>" ) ; 

SayMyABCs( ) ; 

$count = $count + 1; 

print("Now I've made $count function cal 1 ( s ) . <BR>" ) ; 



The intent of SayMyABCs ( ) is to print a sequence of letters. (The functions chr( ) andord() trans- 
late between letters and their numeric ASCII codes — we use them here just as a trick to generate 
letters in sequence.) The output of this code is: 

ABCDEFGHI J 

Now I know 10 letters 

Now I've made 1 function call(s). 

ABCDEFGHI J 

Now I know 10 letters 

Now I've made 2 function call(s). 



Both the function definition and the code outside the function make use of variables called $ c o u n t , 
but they refer to different variables and do not clash. 

The default behavior of variables assigned inside functions is that they do not interact with the out- 
side world; they act as though they are newly created each time the function is called. Both of these 
behaviors, however, can be overridden with special declarations. 



Global versus local 

The scope of a variable defined inside a function is local by default, meaning that (as we explained 
in the previous section) it has no connection with the meaning of any variables outside the function. 
Using the global declaration, you can inform PHP that you want a variable name to mean the same 
thing as it does in the context outside the function. The syntax of this declaration is simply the word 
global, followed by a comma-delimited list of the variables that should be treated that way, with a 
terminating semicolon. To see the effect, consider a new version of the previous example. The only 
difference is that we have declared $count to be global, and we have removed its initial assignment 
to zero inside the function: 



function SayMyABCs2 () 
{ 

global $count; 
while ($count < 10) 
t 

pr i nt ( ch r ( ord ( ' A ' ) + Icount)); 
$count = Icount + 1 ; 

1 

pri nt ( " <BR>Now I know Icount 1 etters<BR>" ) ; 
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} 

$count = 0; 
SayMyABCs2( ) ; 
$count = $count + 1 ; 

print("Now I've made $count function cal 1 ( s ) . <BR>" ) ; 
SayMyABCs2( ) ; 
$count = $count + 1 ; 

print("Now I've made $count function cal 1 ( s ) . <BR>" ) ; 
Our revised version prints the following browser output: 
ABCDEFGH I J 

Now I know 10 letters 

Now I've made 11 function call(s). 

Now I know 11 letters 

Now I've made 12 function call(s). 

This is buggy behavior, and the global declaration is to blame. There is now only one $ c o u n t 
variable, and it is being increased both inside and outside the function. When the second call to 
SayMyABCs ( ) happens, $count is already 11, so the loop that prints letters is never entered. 

Although this example shows gl obal to bad advantage, it can be quite useful, especially because (as 
we'll see in Chapter 6) PHP provides some variable bindings to every page even before any of your 
own code is executed. It can be helpful to have a way for functions to see these variables without the 
bother of passing them in as arguments with each call. 

Static variables 

By default, functions retain no memory of their own execution, and with each function call local 
variables act as though they have been newly created. The static declaration overrides this behav- 
ior for particular variables, causing them to retain their values in between calls to the same function. 
Using this, we can modify our earlier function SayMyABCs 2 ( ) to give it some memory: 

function SayMyABCs3 () 
{ 

static $count = 0; //assignment only if first time called 
$1 imit = $count + 10; 
while ( $ c o u n t < $ 1 imit) 
{ 

print(chr(ord('A') + $count)); 
Icount = $count + 1; 

) 

pri nt( "<BR>Now I know $count 1 etters<BR>" ) ; 

} 

$count = 0; 
SayMyABCs3( ) ; 
Scount = $count + 1 ; 
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print("Now I've made $count function call (s) .<BR>") ; 
SayMyABCs3( ) ; 
$count = $count + 1; 

print("Now I've made $count function call (s) .<BR>" ) ; 
This memory-enhanced version gives us the following output: 
ABCDEFGHI J 

Now I know 10 letters 

Now I've made 1 function call(s). 

KLMNOPQRST 

Now I know 20 letters 

Now I've made 2 function call(s). 

The static keyword allows for an initial assignment, which has an effect only if the function has not 
been called before. The first time SayMyABCs3( ) executes, the local version of $count is set to zero. 
The second time the function is called, it has the value it had at the end of the last execution, so we 
are able to pick up our studies where we left off. Notice that changes to $ count outside the function 
still have no effect on the local value. 



Exceptions 

You've already seen some fairly primitive error handling in the form of d i e ( ) , and you might well 
imagine the custom error handling possibilities implied by the combination of control structures 
and basic use of p r i n t ( ) or p r i n t f ( ) commands (more on this in Chapter 26). However, in prior 
versions of PHP, a chief complaint was the lack of standardized means for handling errors, and sepa- 
rating that means from the application code itself. Enter Exceptions. 

Exceptions use the try, catch syntax similar to Java or Python, although programmers using 
those languages will note the absence of f i nal 1 y . 

Let's start with a simple example that has no error handling at all: 

function pri nt_header ( $t i tl e , $keywords, $descri pti on ) ( 
print( "<HTMLXHEAD>" ) ; 
print( "<TITLE>$title</TITLE>") ; 

print("<META NAME=\ " KeywordsX " CONTENT=\"$keywords\">" ) ; 

pri nt ( " <META NAME=\ " Descri pti on\ " CONTENT=\"$description\">") ; 

pri nt( "</HEADXBODY>" ) ; 

} 

pri nt_header( ' My Page', 
'PHP, Programming, Beer', 
"); 

The custom function pri nt_header( ) is designed to make it easy for us to place a standardized, 
search engine-friendly header at the top of each page. However, we've left the description variable 
undefined, which will not yield an error, but will leave us without a meaningful description for our 
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page. Unfortunately, because the function is essentially called correctly and PHP is forgiving in nature, 
we may never know that we've left off this important detail. Some form of error handling is necessary 
to point this out, and Exceptions provide a handy way of dong so. Consider this revised code: 

function pri nt_header ( $ti tl e , $keywords, $descri pti on ) I 

i f ( strl en ( $descri pti on ) < 40) 

throw new Exception('A reasonable description length is 
requi red<BR> ' ) ; 

pri nt( "<HTMLXHEAD>" ) ; 

print("<TITLE>$title</TITLE>" ) ; 

print("<META NAME=\"Keywords\" CONTENT=\"$keywords\">" ) ; 
print("<META NAME=\ " Descri pt i on\ " CONTENT=\"$description\">") ; 
pri nt ( "</HEADXBODY>" ) ; 

} 



try ( 

pri nt_header( ' My Page', 
'PHP, Programming, Beer', 

I catch (Exception $e) { 
echo($e->getMessage( ) ) ; 

} 



The first new thing in our revised function is a simple test in line 2 suggesting an appropriate mini- 
mum length for the Sdescription variable. The line immediately following initiates an instance of 
the Excepti on class with the message suggested by the quoted value. 



You can create your own classes and extensions of existing classes, including those for 
exception handling. PHP gives you Exception for free. We'll go into much greater depth 
on the subject of classes in Chapter 20 and exception handling itself in Chapter 30. 



Next, instead of simply calling the function, we've enclosed the function in a new control structure, 
the try. . .catch block. If we execute the code as written, PHP first tries to execute the function 
as described, then it terminates execution almost immediately, because the $description variable 
has failed our simple test. At this point, the script can continue execution after the try. . .catch 
block, or it can be terminated with di e ( ) or exi t ( ) . 

Multiple exceptions can be defined in a single function. This is a good idea because it yields more 
specific information about what exactly happened. Because execution stops with the first exception, 
only this exception will be caught. 

I C r ^ rj-TC*^ rj p'^ Exceptions are a huge topic; they're outlined here so that you can start using them imme- 
wBJ^^mJmS^ diately. You'll find nods to exceptions throughout this book, but they are covered in 
depth in Chapter 30. 
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Function Scope 

Although the rules about the scope of variable names are fairly simple, the scoping rules for function 
names are even simpler. There is just one rule in PHP6: Functions must be defined once (and only 
once) somewhere in the script that uses them. (See the following note about differences between 
this behavior and PHP3.) The scope of function names is implicitly global, so a function defined in 
a script is available everywhere in that script. For clarity's sake, however, it is often a good idea to 
define all your functions before any code that calls those functions. 

p .- r f\* F In PHP3, functions could be used only after they were defined. This meant that the safest 

practice was to define (or include the definitions of) all functions early in a given script, 
before actually using any of them. Beginning with PHP4, scripts are precompiled before being run, 
and one effect of this precompilation is that the compiler discovers all function definitions before actu- 
ally running the code. This means that functions and code can appear in any order in a script, as long 
as all functions are defined once (and only once). 



Include and require 

It's very common to want to use the same set of functions across a set of web site pages, and the usual 
way to handle this is with either includeorrequire, both of which import the contents of some 
other file into the file being executed. Using either one of these forms is vastly preferable to cloning 
your function definitions (that is, repeating them at the beginning of each page that uses them); when 
you want to modify your functions, you will have to do it only once. (We covered these forms in 
Chapter 3, but they are worth reviewing here in the context of including function definitions.) 

For example, at the top of a PHP code file we might have lines like: 

i ncl ude "basi c-f uncti ons . i nc" ; 
include "advanced-function.inc"; 

(.. code that uses basic and advanced functions ..) 

which import two different files of function definitions. (Note that parentheses are optional with 
both i ncl u d e ( ) and r e q u i r e ( ) .) As long as the only things in these files are function definitions, 
the order of their inclusion does not matter. 

Both i ncl ude and requi re have the effect of splicing in the contents of their file into the PHP code 
at the point that they are called. The only difference between them is how they fail if the file cannot 
be found. The include construct will cause a warning to be printed, but processing of the script 
will continue; requi re, on the other hand, will cause a fatal error if the file cannot be found. 

"pTp r- " ' F Note that i ncl ude and requi re are now more similar in their behavior than they used 

■ - • to be. Prior to PHP 4.0.2, requi re had its file contents spliced in statically, before the 
actual execution of the page; whereas the contents from i ncl ude were spliced in dynamically as the 
page executed. Among other things, this led to subtle differences in behavior when the i ncl ude/ 
requi re form was in conditional code. Now, however, both i ncl ude and requi re have the same 
dynamic behavior. This means, for example, that if an include/require form is in a loop executed 
10 times, 10 inclusions will be made. 
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Including only once 

Sometimes you really want a file to be included once, but not more than once. This is true most 
often in the case of function definitions. For example, two different function definition files might, 
in turn, include the same file of utility functions — if a top-level page includes both of these files, 
the utility functions might be included twice, leading to complaints from PHP that functions are 
being defined twice. 

To the rescue come i ncl ude_once and requi re_once, which act just like their counterparts except 
that they will not include a file named by a given string if that file has already been included. It's usu- 
ally better to use the _once version, in general, for including function and class definition files. 



The include path 

When you i ncl ude a filename, PHP searches for a file by that name in the directories specified in 
the i n c 1 u d e_p a t h (which is settable in your p h p . i n i file). The default path includes the same 
directory as the one the top-level code page is in. See Chapter 29 for details about how to add loca- 
tions to your include path. 

In situations where a single instance of PHP serves several virtual sites, it's generally easier and less 
confusing to PHP to use the $_SERVER superglobal array to specify the location of an i ncl ude file: 

incl ude_once($_SERVER[ ' D0CUMENT_R00T ' ] . "/path/ to/ i ncl ude_f i 1 e" ) ; 

'■- - I o"*' N 'f ' Remember that included (and required) files are parsed by default in HTML mode rather 

than in PHP mode. This means that any included file meant to be interpreted as PHP needs 
to have the usual PHP tags at the beginning and end, though the end tags aren't technically required. 



Recursion 

Some compiled languages, like C and C++, impose somewhat complex ordering constraints on how 
functions are defined. To know how to compile a function, the compiler must know about all the 
functions that the function calls, which means the called functions must be defined first. So what 
do you do if two functions each call the other or if one function calls itself? Issues like this led the 
designers of C to a separation of function declarations (or prototypes) from function definitions (or 
implementations). The idea is that you use declarations to inform the compiler in advance about the 
types of arguments and return types of the functions you plan to use, which is enough information 
for the compiler to handle the actual definitions in any order. 

In PHP, this problem goes away, and so there is no need for separate function prototypes. As long 
as each function that is called is defined once (and only once) in the current code file or one that is 
included in the course of the current script's execution, PHP will have no problem resolving func- 
tion calls, regardless of the interleaving of function calls and definitions. 

This means that recursive functions (functions that call themselves) are no problem in PHP4. For 
example, we can define a recursive function and then immediately call it: 

function countdown ($num_arg) 
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{ 

if ($num_arg > 0) 
1 

pri nt (" Count i ng down from $num_a rg<BR> " ) ; 
countdown ( $num_a rg - 1); 

} 

} 

countdown ( 10 ) ; 
This produces the browser output: 
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As with all recursive functions, it's important to be sure that the function has a base case (a nonrecur- 
sive branch) in addition to the recursive case, and that the base case is certain to eventually occur. If 
the base case is never invoked, the situation is much like awhile loop where the test is always true 
— we will have an infinite loop of function calling. In the case of the preceding function, we know 
that the base case will happen, because every invocation of the recursive case reduces the countdown 
number, which must eventually become zero. Of course, this assumes that the input is a positive inte- 
ger rather than a negative number or a double. Notice that our "greater than zero" test guards against 
infinite recursion even in these cases, whereas a "not equal to zero" test would not. 

Similarly, mutually recursive functions (functions that call each other) work without a hitch. For exam- 
ple, the following definitions plus function call: 

function countdown_f i rst ($num_arg) 
{ 

if ($num_arg > 0) 
( 

pri nt (" Count i ng down (first) from $num_a rg<BR> " ) ; 
countdown_second ( $num_a rg - 1); 




function countdown_second ($num_arg) 
{ 

if ($num_arg > 0) 
i 

pri nt (" Count i ng down (second) from $num_arg<BR>" ) ; 
countdown_f i rst( $num_arg - 1); 

1 
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count down_f i rst ( 5 ) ; 
produce the browser output: 

from 5 

from 4 
from 3 

from 2 
from 1 



Counting do 

Counting do 

Counting do 

Counting do 

Counting do 



wn (first) 

wn (second) 

wn (first) 

wn (second) 

wn (first) 



Summary 

PHP has a C-like set of control structures, which branch or loop depending on the value of Boolean 
expressions, which in turn can be combined using Boolean operators (and, or, xor, ! , &&, | |). The 
structures i f and swi tch are used for simple branching; while, do-while, and for are used for 
looping, and exi t ( ) or d i e ( ) terminates script execution. 

Most of the power of PHP resides in the large number of built-in functions provided by PHP's benev- 
olent army of open source developers. Each of these functions should be documented (albeit briefly) 
in the online manual at www. php.net. 

You can also write your own functions, which are then used in exactly the same way as the built-in 
functions. Functions are written in a simple C-style syntax, as in the following: 

function my_f unction ($argl, $arg2, ..) 
{ 

statementl ; 
statement2; 

return ( $val ue ) ; 

} 

User-defined functions can use arguments of any PHP type and can also return values of any type. 
The types of arguments and return values do not need to be declared. 

In PHP, the ordering of function definitions and function calls makes no difference, as long as every 
function that is called is defined exactly once. There is no need for separate function declarations or 
prototypes. Variables assigned inside a function are local to that function, unless specified otherwise 
with the gl obal declaration. Local variables maybe declared to be static, which means that they 
hold onto their values in between function calls. 

Finally, with our brief treatment of exceptions, we're well on our way to writing thoughtful friendly 
code that uses standardized error handling. 
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In this chapter, we'll briefly discuss some things you need to know 
about passing data between web pages. Some of this information is not 
specific to PHP but is a consequence of the PHP/HTML interaction or 
of the HTTP protocol itself. 



HTTP Is Stateless 

The most important thing to recall about the way the web works is that the 
HTTP protocol itself is stateless. If you are a poetic soul, you might say that 
each HTTP request is on its own, with no direction home, like a complete 
unknown . . . you know how the rest goes. 

For the less lyrical among us, this means that each HTTP request — in 
most cases, this translates to each resource (HTML page, . j pg file, style 
sheet, and so on) being asked for and delivered — is independent of all the 
others, knows nothing substantive about the identity of the client, and has 
no memory. 

Even if you design your site with very strict one-way navigation (Page 1 
leads only to Page 2, which leads only to Page 3, and so on), the HTTP 
protocol will never know or care that someone browsing Page 2 must have 
come from Page 1. You cannot set the value of a variable on Page 1 and 
expect it to be imported to Page 2 by the exigencies of HTTP itself. You 
can use HTTP to display a form, and someone can enter some information 
using it — but unless you employ some extra means to pass the informa- 
tion to another page or program, the variable will simply vanish into the 
ether as soon as you move to another page. 



IN THIS CHAPTER 



HTTP is stateless 



GET arguments 



A better use for GET-style URLs 



POST arguments 
Formatting form variables 
PHP superglobal arrays 
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This is where a form-handling technology like PHP comes in. PHP will catch the variable tossed 
from one page to the next and make it available for further use. PHP happens to be unusually good 
at this type of data-passing function, which makes it fast and easy to employ for a wide variety of 
web site tasks. 

HTML forms are mostly useful for passing a few values from a given page to one single other page of 
a web site. There are more persistent ways to maintain state over many pageviews, such as cookies 
and sessions, which we cover in Chapter 24. This chapter will focus on the most basic techniques of 
information-passing between web pages, which utilize the GET and POST methods in HTTP to create 
dynamically generated pages and to handle form data. 



GET Arguments 

The GET method passes arguments from one page to the next as part of the Uniform Resource 
Indicator (you may be more familiar with the term Uniform Resource Locator, or URL) query string. 
When used for form handling, GET appends the indicated variable name(s) and value(s) to the URL 
designated in the ACTION attribute with a question mark separator and submits the whole thing to 
the processing agent (in this case a web server). 

This is an example HTML form using the GET method (save the file under the name sportselect 
. html): 

<!D0CTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/ 

TR/html4/strict.dtd"> 

<HTML> 

<HEAD> 

<TITLE>A GET method example, part K/TITLE) 
</HEAD> 

<B0DY> 

<F0RM ACTION="sports.php" METHOD="GET"> 
<P>Choose your favorite sport:<BR> 
<SELECT NAME="Sport"> 

<0PTI0N VALUE="Basebal 1 ">Basebal 1< /OPTION) 
<OPTION VALUE="Basketbal 1 ">Basketbal 1 < /OPTION) 
<OPTION VALUE="Footbal 1 ">Footbal 1 < /OPTION) 
<OPTION VALUE="Ice Hockey">Ice Hockey</OPTION> 
<OPTION VALUE="Racing">Auto Raci ng</OPTION> 
<OPTION VALUE="Soccer">Soccer< /OPTION) 
</SELECT> 

<PXINPUT TYPE="submit" NAME="Submi t" VALUE="Sel ect"X/P> 

</FORM> 

</BODY> 

</HTML> 
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When the user makes a selection and clicks the Submit button, the browser agglutinates these ele- 
ments in this order, with no spaces between the elements: 

■ The URL in quotes after the word ACTION (http : //I ocal host/basebal 1 . php) 

■ A question mark (?) denoting that the following characters constitute a GET string. 

■ A variable NAME, an equal sign, and the matching V ALU E (Team=Cubbi es) 

■ An ampersand (&) and the next NAME-VALUE pair (Submi t=Sel ect); further name-value 
pairs separated by ampersands can be added as many times as the server query-string- 
length limit allows. 

The browser thus constructs the URL string: 

http ://<your-server-name>/ sports. php?Sport=I ce+Hockey&Submi t=Sel ect 

It then forwards this URL into its own address space as a new request. The PHP script to which the 
preceding form is submitted (sports, php) will grab the GET variables from the end of the request 
string, stuff them into the $„GET superglobal array (explained in a moment), and do something use- 
ful with them — in this case, plug one of two values into a text string. 

The following code sample shows the PHP form handler for the preceding HTML form: 

<!D0CTYPE HTML PUBLIC " -/ /W3C//DTD HTML 4.01//EN" "http://www.w3.org/ 

TR/html4/strict.dtd"> 

<HTML> 

<HEAD> 

<TITLE>A GET method example, part 2</TITLE> 
<STYLE TYPE="text/css"> 

<!-- 

BODY {font-size: 24pt;} 

--> 

</STYLE> 
</HEAD> 

<BODY> 

<P>You've indicated that you like 
<?php echo $_GET['Sport']; ?>!</P> 
</BODY> 
</HTML> 

Note that the value inputted into the previous page's HTML form field named "Spo rt" is now avail- 
able in a PHP variable called $_GET[ ' Sport ' ] . Finally, you should see a page that says You've indi- 
cated that you like Ice Hockey! in big type. 
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At this point, it makes some sense to explain just how to access values submitted from 
page to page. This chapter discusses the two main methods for passing values: GET and 
POST (there are others, but they are not covered until Part III). Each method has an associated super- 
global array, explained in more depth in Chapter 8, which can be distinguished from other arrays by the 
underscore that begins its name. Each item submitted via the GET method is accessed in the handler via 
the $ GET array; each item submitted via the POST method is accessed in the handler via the $__P0ST 
array. The syntax for referencing an item in a superglobal array is simple and 100 percent consistent: 

$_ARRAY_NAME [ ' i ndex_name ' ] 

where the i ndex_name is the name part of a name-value pair (for the GET method), or the name of an 
HTML form field (for the POST method). As in the preceding example, $_GET[ ' Sport ' ], indicates the 
value of the form select field called 'Sport', sent by the GET operation in the original file. You must 
use the array appropriate to the method used to send data. In this case, $_P0ST[ ' Sport ' ] is unde- 
fined because no data was POSTed by the original form. 

The GET method of form handling offers one big advantage over the POST method: It constructs an 
actual new and differentiable URL query string. Users can now bookmark this page. The result of 
forms using the POST method is not bookmarkable. 

Just because you can achieve the desired functionality with GET arguments doesn't mean you should. 
The disadvantages of GET for most types of form handling are so substantial that the original HTML 
4.0 draft specification deprecated its use in 1997. These flaws include: 

■ The GET method is not suitable for logins because the username and password are fully vis- 
ible onscreen as well as potentially stored in the client browser's memory as a visited page. 

■ Every GET submission is recorded in the web server log, data set included. 

■ Because the GET method assigns data to a server environment variable, the length of the URL 
is limited. You may have seen what seem like very long URLs using GET — but you really 
wouldn't want to try passing a 300-word chunk of HTML-formatted prose using this method. 

The original HTML spec called for query strings to be limited to 255 characters. Although 
this stricture was later loosened to mere encouragement of a 255-character limit, using a 
longer string is asking for trouble. 



CAUTION 



The GET method of form handling had to be reinstated by the W3C after much outcry, largely 
because of the bookmarkability factor. Despite that it's still implemented as the default choice for 
form handling in all browsers, GET now comes with a strong recommendation to deploy it in idem- 
potent usages only — in other words, those that have no permanent side effects. Putting two and two 
together, the single most appropriate form-handling use of GET is the search box. Unless you have a 
compelling reason to use GET for non-search-box form handling, use POST instead. 



A Better Use for GET-Style URLs 

Although the actual GET method of form handling is deprecated, the style of URL associated with it 
turns out to be very useful for site navigation. This is especially true for dynamically generated sites 
such as those often constructed with PHR because the appended-variable style of URL works par- 
ticularly smoothly with a template-based content-development system. 
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As an illustration, imagine you are the proud proprietor of an information-rich web site about solar 
cars. You've toiled long and hard over informative and attractive pages such as these: 

S us pen si on_desi gn . html 
Windtunnel_testing. html 
f n' cti on_bra ki ng . html 

But as your site grows, a flat-file site structure like this can take a lot of time to administer, as even 
the most trivial changes must be repeated on every page. If the structure of these pages is very simi- 
lar, you might want to move to a template-based system with PHP. 

You might decide to utilize a single template with separate text files for each topic (containing infor- 
mation, photos, comments, and so on): 

t o p i c . p h p 

s us pens i on_des i gn . i nc 

windtunnel_testing.inc 

friction_braking.inc 

Or you might decide you needed a larger, more specialized choice of template files: 

V e h i c 1 e„s t r u c t u r e . p h p 

Tubul a r_f rames . i nc 
Mechanical_systems.php 

Friction_braking.inc 
Electrical_systems.php 

Sol a r_a r ray . i nc 
racing.php 

race_strategy . i nc 

A simple template file might look something like this (because we haven't included the necessary 
. i n c text files, this example will not actually work): 

<!D0CTYPE HTML PUBLIC " - / /W3C//DTD HTML 4.01//EN" "http://www.w3.org/ 

TR/html4/strict.dtd"> 

<HTML> 

<HEAD> 

<TITLE>Sol ar-car topi cs</TITLE> 
<STYLE TYPE="text/css"> 

<!-- 

BODY (font: verdana; font-size: lZpt] 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 C E L L PADD I N G=0 W I DTH= " 1 00% " > 

<TR> 

<!-- Navbar, with Get-style URLs. --> 
<TD ALIGN=CENTER VALIGN=T0P> 
<P> 
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<A HREF=" mechanical _syst em s.php?Name=fricti on_bra ki ng"> 
<B>Friction braki ng</BX/A> 
<BR> 

<A HREF="mechanical_systems.php?Name=steering"> 
<B>Steering</BX/A> 
<BR> 

<A HREF="mechanical_systems.php?Name=suspension"> 
<B>Suspension</BX/A> 
<BR> 

<A HREF=" mechanical _syst ems. php?Name=ti res " > 
<B>Tires and wheel s</BX/A> 
<BR> 

</P> 
</TD> 



<!-- Main body of content --> 

<TD AL I GN = LE FT VALIGN=TOP> 

<?php include($_GET['Name'] . 

</TDX/TRX/TABLE> 

</B0DY> 

</HTML> 



' i n c " ) ; ? > 



Notice that the links on the navbar, when clicked, will be handled by the browser as if they were the 
product of a GET submission. 

But even with this solution, you still have to tend part of your garden by hand: making sure that each 
i n c 1 u d e file is properly formatted in HTML, adding a new link to the navbar each time you add a new 
page to the site, and other such chores. Following the general rule to separate form and content as much 
as is feasible, you might choose to go to another level of abstraction with a database. In that case, a URL 
such as http : / /www .example.com/topic.php?topicID=2 would point to a PHP template that 
makes database calls. (Using a number variable rather than a word makes for faster database interac- 
tion.) This system could also automatically add a link to the navbar whenever you added new topics 
to the database, so it could produce web pages entirely without ongoing human intervention (all right, 
maybe entirely is an exaggeration — but with significantly fewer person-hours of grunt labor). 



POST Arguments 

POST is the preferred method of form submission today, particularly in nonidempotent usages (those 
that will result in permanent changes), such as adding information to a database. The form data set 
is included in the body of the form when it is forwarded to the processing agent (in this case, PHP). 
No visible change to the URL will result according to the different data submitted. 

The POST method has one primary advantage: 

■ There is a much larger limit on the amount of data that can be passed (a couple of mega- 
bytes rather than a couple of hundred characters). 



104 



Passing Information with PHP 



6 



POST has these disadvantages: 

■ The results at a given moment cannot be bookmarked. 

■ Browsers exhibit different behavior when the visitor uses their Back and Forward naviga- 
tion buttons within the browser. 

There is a misguided belief that POST is more secure than GET. In reality, neither offers any more 
security than the other. The visitor can still view variables and data being sent with a POST just as 
they can with a GET. The only difference is that the data doesn't show up in the address bar. This 
doesn't mean that it's hidden. Data sent with a POST can be viewed and altered by the web site user. 

The first and most important rule of programming, especially web programming is: 

Never Trust Input 

Always assume that the visitor has either maliciously or accidentally altered the data being passed 
into your application, and validate the data. 

Only when the request is secured using SSL or TLS or some other form of encryption is the form 
data somewhat secure. Nevertheless, the end user or visitor can still see and alter the data. SSL 
merely encrypts the data in transit, preventing prying eyes on the network from looking at it. SSL 
does nothing to prevent the visitor from changing form data. 

I'll cover much more about security throughout the book. I believe security needs to be included in 
every aspect of programming, and, therefore, you'll see security tips when appropriate and within 
context, rather than trying to make sense of them in a specific chapter. Chapter 28 will examine 
PHP security, concentrating on overall best practices and also server security, as well. 



Get and Post Both 




id you know that with PHP you can use both GET and POST variables on the same page? You might want 
to do this for a dynamically generated form, for example. 



But what if you (deliberately or otherwise) use the same variable name in both the GET and the POST variable 
sets? PHP keeps all ENVIRONMENT, GET, POST, COOKIE, and SERVER variables in the $GL0BALS array if you 
have set the regi ster_gl obal s configuration directive to "on" in your php . ini file (doing so creates a 
security risk). If there is a conflict, it is resolved by overwriting the variable values in the order you set, using the 
va ri abl es_order option in php. ini. Later trumps earlier, so if you use the default " EG PCS" value, cookies 
will triumph over POSTs that will themselves obliterate GETs. You can control the order of overwriting by simply 
changing the order of the letters on the appropriate line of this file, or even better, turning regi s ter_gl obal s 
off and using the new PHP superglobal arrays instead. See the section on superglobals later in this chapter. 
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Formatting Form Variables 

PHP is so efficient at passing data around because the developers made a very handy but (in theory) 
slightly sketchy design decision. PHP automatically, but invisibly, assigns the variables for you on 
the new page when you submit a data set using GET or POST. Most of PHP's competitors make you 
explicitly do this assignment yourself on each page; if you forget to do so or make a mistake, the 
information will not be available to the processing agent. PHP is faster, simpler, and mostly more 
goof-proof. 

But because of this automatic variable assignment, you need to always use a good NAME attribute for 
each INPUT. NAME attributes are not strictly necessary in HTML proper — your form will render fine 
without them — but the data will be of little use because the HTML form-field NAME attribute will 
be the variable name in the form handler. 



In other words, in this form: 

<F0RM ACTION="<?php echo $_SERVER[ ' PHP_SELF' ] ; ?>" 
METH0D="P0ST"> 

<INPUT TYPE="text" NAME="emai 1 "> 

< INPUT TYPE="submit" NAME="submi t" VALUE="Send"> 

</F0RM> 



the text field named email will cause the creation of a PHP variable called $„P0ST[ 'email ' ] 
when the form is submitted. Similarly, the submit button will lead to the creation of a variable called 
$_P0ST[ ' submi t ' ] on the next page. The name you use in the HTML form will be the name of 
your variable in the PHP form handler. 



i r, - : 


mvi 1 







$HTTP_POST_VARS, $HTTP_SERVER_VARS, and the whole family of these long-form 
predefined variables were deprecated in PHP5. If you are already an experienced PHP 
programmer, perhaps with a large body of previously written code lying around, you might want to 
think about rewriting now for backward compatibility. They are supported for the time being, but their 
days are numbered. Use $_P0ST, $„GET, and friends instead. 

Remember that you cannot use a variable name beginning with a number — so you should not 
name your form field something like 5 (you laugh, but we've seen people try to do it) — and PHP 
variable names are case sensitive. Also, please try to use informative variable names rather than a 
succession of form fields named my va r and e. 

It's a good idea to standardize how you name form variables, to make your code more 
readable and so that you spend less time flipping back to the form itself when you are 
supposed to be writing code to process that form. For example, you might precede all form variables 
with f rm to indicate their source. You might then consistently use the first few letters of each identify- 
ing word for what a field does, for example, f rmNameFi rst, f rmOf f i ceAdd, f rmHomeAdd, and so 
on. The specific standard you set is less important than having a standard to begin with. 
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Another thing to keep in mind when creating your HTML forms is that, if you ever want this form to 
be displayed with prefilled inputs, you need to set the VALUE attribute. This is particularly relevant 
to two kinds of forms: those that are used to edit data from a database, and those that are intended 
to possibly be submitted more than once. The latter case is very common in situations where a form 
should redisplay on error with values already prefilled — for instance, a registration form that will 
not work until the user provides a valid e-mail address or other required data. 

For example, the form in Listing 6-1 (which represents a retirement savings calculator) is designed 
to be submitted multiple times while the user fiddles around with the values. Every time you submit 
the form, the values from the previous go-round will be filled in for you automatically. Note the use 
of the VALUE attribute in the form fields in this code sample. 



LISTING 6-1 



Form with prefilled values (retirement_calc.php) 

<!D0CTYPE HTML PUBLIC " -/ /W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/ 

strict. dtd"> 

<HTML> 

<HEAD> 

<TITLE>A POST example: retirement savings worksheet</TITLE> 
<STY LE TYPE="text/css"> 

<! -- 

BODY {font-size: 14pt) 

.heading (font-size: 18pt; color: red) 

--> 

</STYLE> 
</HEAD> 

<?php 

// This test, along with the Submit button value in the form 
// below, will check to see if the form is being rendered for 
// the first time (in which case it will display with only the 
// default annual gain filled in). 

if (! IsSet($_POST[ 'Submit' ] ) || $_P0ST[ ' Submi t ' ] != 'Calculate') 
{ 

$_POST[ ' CurrentAge ' ] = ""; 
$„POST[ ' Reti reAge' ] = ""; 
$_POST['Contrib'] = ""; 
$Total = 0; 
$AnnGain = 7; 
) else { 

$AnnGain = $_P0ST[ ' AnnGa i n ' ] ; 

$Years = $_P0ST[ ' Reti reAge ' ] - $_P0ST[ ' CurrentAge '] ; 
$YearCount = 0; 
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$Total = $_P0ST[ 'Contrib' ] ; 

while ($YearCount <= $Years) { 

$Total = round($Total * (1.0 + $AnnGa i n/100 ) + 
$_P0ST['Contrib']); 

$YearCount = $YearCount + 1; 

} 

} 

?> 

<B0DY> 

<D I V ID="Di'vl" class = "heading"> 

A retirement-savings cal cul ator</DIV> 

<P cl ass=bl urb>Fi 1 1 in all the values (except "Nest Egg") 
and see how much money you'll have for your retirement 
under different scenarios. You can change the values and 
resubmit the form as many times as you like. You must fill 
in the two "Age" variables. The "Annual return" variable has 
a default inflation-adjusted value (7% = 8% growth minus 1% 
inflation) which you can change to reflect your greater 
optimism or pess i mi sm . </ P> 

<F0RM ACTI0N="<?php echo $_SERVER[ 1 PHP_SELF ' ] ; ?>" 

METH0D="P0ST"> 

<P>Your age now: 

<INPUT TYPE="text" SI ZE=5 NAME="CurrentAge" 
VALUE="<?php echo $_P0ST[ ' CurrentAge ' ] ; ?>"> 
<P>The age at which you plan to retire: 
<INPUT TYPE="text" SIZE=6 NAME="Reti reAge" 
VALUE="<?php echo $_P0ST[ ' Reti reAge '] ; ?>"> 
<P>Annual contribution: 

<INPUT TYPE="text" SIZE=15 NAME="Contri b" 
VALUE="<?php echo $_P0ST[ ' Contri b ' ] ; ?>"> 
<P>Annual return: 

<INPUT TYPE="text" SIZE=5 NAME="AnnGain" 
VALUE="<?php echo $AnnGain; ?>"> % 
<BRXBR> 

<PXB>NEST EGG</B>: <?php echo $Total ; ?> 

<PXINPUT TYPE="submit" NAME="Submit" VALUE="Cal cul ate"> 

</F0RM> 

</B0DY> 

</HTML> 



Figure 6-1 shows the result ol the Listing 6-1. 
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FIGURE 6-1 



A form using the POST method with VALUE attributes 



• A POST example: retirement Sdvirvgi worksheet - Mod I la firefcK 



JSI*I 



A retirement-savings calculator 

Fill in all the values (except "Nest Egg") and see how much money you'll 
have for your retirement under different scenarios. You can change the 
values and resubmit the form as many times as you like. You must fill in 
the two "Age" variables. The "Annual return" variable has a default 
inflation- adjusted value (7% - 8% growth minus 1% inflation) which you 
can change to reflect your greater optimism or pessimism. 



Your age now: \n~ 



The age at which you plan to retire: [55 
Annual contribution: 1 5 1 so 
Annual return: [7 % 




Consolidating forms and form handlers 

As you can see in the preceding example, it is often handy to make the HTML form and the form 
handler into one script. This practice has many advantages, such as making it easier to change the 
name of the file without harming functionality, making it easier to display error messages and pre- 
filled form fields, and achieving better control over your variable namespace. Suppose that you are 
making a login form that redisplays with an error message if the login is unsuccessful. If you have 
separate forms and form handlers, you'll probably have to do something yucky with GET vars and 
redirection. If you consolidate, it's very simple to control the display without these machinations. 




To see how these techniques can be used with data from MySQL, see Chapter 17. 



When you consolidate, generally the form-handling code should come before the form display. This 
order may be something of a shift in thinking for those who are used to writing the form before the 
handler, but if you think it through, you will see the logic of the practice. You have to give yourself 
an opportunity to set variables and make choices before you can decide what to show the user. This 
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is especially relevant if you will be redirecting the user to a different page under certain circum- 
stances, via the header ( ) function, because this decision point must come before any HTML out- 
put has been displayed to the browser. 



PHP Superglobal Arrays 

A change that has been coming for a long time in PHP is the gradual phasing out of automatic global 
variables in favor of superglobal arrays, which were introduced in PHP4. Understanding superglobal 
arrays before you understand arrays may present difficulties; if so, we recommend that you read 
Chapter 8 and come back to this section later. 

In the good old days before PHP4.1, you could write a piece of code like this and expect it to work: 
<?php 

if ( i sSet ( $s ubmi t ) ) { 

echo $ema i 1 ; 
I else ( 
?> 

<F0RM ACTION="<?php echo $PHP_SELF; ?>" METH0D="P0ST"> 

<INPUT TYPE="text" NAME="emai 1 "> 

< INPUT TYPE="submit" NAM E="s ubmi t" VALUE="Send"> 

</F0RM> 

All GET, POST, COOKIE, ENVIRONMENT, and SERVER variables were made global by the regi ster_ 
g 1 o b a 1 s directive in p h p . i n i and were directly accessible by their names by default. 

The PHP team decided to phase out the practice of registering globals, forcing everyone to call these 
variables as indices in an array (for example, $_P0ST[ 'secretpassword']). This had already been 
possible in PHP4, via arrays named $HTTP_GET_VARS, $HTTP_POST_VARS, $HTTP_POST_VARS, 
and so on, but few developers had used this syntax; frankly, it was a lot of extra keystrokes for a 
small increase in security. So the PHP team also took this opportunity to rename these arrays with 
shorter names: $_GET, $_P0ST, $_C00KIE, $„ENV, and $_SERVER. 

These superglobal arrays also have one cool feature that may ameliorate some pain: They are auto- 
matically global everywhere. This means, for instance, that you no longer have to pass cookie values 
into a function or declare the $HTTP„C00KI E„VARS array global before you can access those values 
in a function. This will help those who functionalize to the max and will be a small amelioration for 
everyone else. 

As of PHP6, regi ster_gl obal s is officially gone. 
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Summary 

The HTTP protocol is stateless. This means a plain HTML page is incapable of receiving informa- 
tion from any other page. It can be used to pass values via a URL or an HTML form, but a separate 
program called a form handler must step in to recognize and perform actions on the passed values. 
In first-generation web development, these form handlers were Perl or C CGI scripts, but nowadays 
web developers are more likely to use an HTML-embedded programming language such as PHP. 
PHP makes it particularly easy to write form handlers and even to combine them with HTML dis- 
play on a single web page. 

Information is passed between web pages using one of four main methods: GET, POST, a cookie, or 
sessions. GET is mainly used to construct complex URL strings for use with dynamically generated 
pages. Forms are a good way to pass information from one web page to a single other web page. We 
deal with the persistent state methods, cookies, and sessions in Chapter 24. 
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Although images, sound files, videos, animations, and applets make 
up an important portion of the World Wide Web, much of the web 
is still text — one character's worth after another, like this sen- 
tence. The basic PHP data type for representing text is the string. 

In this chapter, we cover almost all PHP's capabilities for manipulating strings 
(although we leave more advanced string functions and the pattern-matching 
power of regular expressions for separate treatment in Chapter 22). We start 
with the basics of strings, then move to the most commonly used operators 
and functions. 



Strings in PHP 

Strings are sequences of characters that can be treated as a unit — assigned 
to variables, given as input to functions, returned from functions, or sent 
as output to appear on your user's web page. The simplest way to specify a 
string in PHP code is to enclose it in quotation marks, whether single quo- 
tation marks (' ) or double quotation marks ("), like this: 

$my_string = 'A literal string'; 
$another_stri ng = "Another string"; 

The difference between single and double quotation marks lies in how 
much interpolation PHP does of the characters between the quote signs 
before creating the string itself. If you enclose a string in single quota- 
tion marks, almost no interpolation will be performed; if you enclose it in 



IN THIS CHAPTER 



Strings in PHP 
String functions 
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double quotation marks, PHP will splice in the values of any variables you include, as well as make 
substitutions for certain special character sequences that begin with the backslash (\) character. For 
example, if you evaluate the following code in the middle of a web page: 

$statement = 'everything I say'; 
$question_l = 

"Do you have to take Sstatement so 1 i tera 1 1 y ? \n<BR>" ; 
$question_2 = 

'Do you have to take $statement so 1 i teral 1 y ? \n<BR> ' ; 
echo $question_l; 
echo $question_2; 

you should expect to see the browser output: 

Do you have to take everything I say so literally? 
Do you have to take Sstatement so 1 i teral ly?\n 



pf j j £j >X' p r For the details on exactly how PHP interprets both singly and doubly quoted strings, see 
~" " the "Strings" section of Chapter 4. 

Interpolation with curly braces 

In most situations, you can simply include a variable in a doubly quoted string, and the variable's 
value will be spliced into the string when it is interpreted. There are two situations where the string 
parser might very reasonably get confused and need more guidance from you. The first situation is 
when your notion of where the variable name should stop is not the same as the parser's, and the 
other occurs when the expression you want to have interpolated is not a simple variable. In these 
cases, you can clear things up by enclosing the value you want interpolated in curly braces: { ) . 

For example, PHP has no difficulty with the following code: 

$sport = ' vol 1 eybal 1 ' ; 

$plan = "I will play $sport in the summertime"; 

The parser in this case encounters the $ symbol, and then begins collecting characters for a vari- 
able name until it runs into the space after $sport. Spaces cannot be part of a variable name, so it 
is clear that the variable in question is Ssport, and PHP successfully finds a value for that variable 
(' vol 1 eyba 1 1 ' ), and splices the value in. 

Sometimes, though, it is not convenient to stop a variable name with a space. Take this example: 

$sportl = ' vol 1 ey ' ; 
$sport2 = ' foot ' ; 
$sport3 = ' basket ' ; 

$planl = "I will play Isportlball in the summertime"; //wrong 
$plan2 = "I will play $sport2ball in the fall"; //wrong 
$plan3 = "I will play $sport3ball in the winter"; //wrong 
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You will not get the desired effect here, because PHP interprets $sportl as part of the variable 
name $sportlball, which is probably unbound. Instead, you need something like: 

$planl = "I will play I $sportl } b a 1 1 in the summertime"; //right 

which asks PHP to evaluate only the variable expression within the braces before interpolating. 

For similar reasons, PHP has difficulty interpolating complex variable expressions, such as multi- 
dimensional arrays and object variables, unless curly braces are used. The general rule is that if you 
have a { immediately followed by a $ , PHP will evaluate the variable expression up until the closing 
} and will interpolate the resulting value into the string. (If you need a literal I $ to appear in your 
string, you can accomplish it by escaping either character with a backslash (\)). 

j-Jp - ^ I See the "Concatenation and Assignment" section later in this chapter for ideas on other 
ways to address challenges like this. 

Characters and string indexes 

Unlike some programming languages, PHP has no distinct character type different from the string 
type. In general, functions that would take character arguments in other languages expect strings of 
length 1 in PHP. 

You can retrieve the individual characters of a string by including the number of the character, start- 
ing at 0, enclosed in curly braces immediately following a string variable. These characters will actu- 
ally be one-character strings. For example, the following code: 

$my_string = "Doubled"; 

for ($index = 0; Sindex < 7; $index++) ( 

$stri ng_to_pri nt = $my_st ri ng ( $i ndex } ; 

p r i n t ( " $ s t r i n g_t o„p r i n t $ s t r i n g_t o_p r i n t " ) ; 

1 

gives the browser output: 
DDoouubbl 1 eedd 

with each character of the string being printed twice per loop. (The number 7 is hardcoded in this 
example only because we haven't yet covered how to find out the length of a string — see the func- 
tion strl en ( ) in the later section "Inspecting strings.") 

String operators 

PHP offers two string operators: the dot (.) or concatenation operator and the .= concatenating 
assignment operator. The concatenating assignment operator is discussed in the next section. The 
concatenation operator, when placed between two string arguments, produces a new string that is 
the result of putting the two strings together in sequence. For example: 

$my_two_cents = "I want to give you a piece of my mind "; 
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$third_cent = " And another thing"; 

pri nt ( $my_two_cents . . $thi rd_cent ) ; 

gives the output: 

I want to give you a piece of my mind ... And another thing 

Note that we are not passing multiple string arguments to the print statement — we are handing it 
one string argument, which was created by concatenating three strings together. The first and third 
strings are variables, but the middle one is a literal string enclosed in double quotation marks. 



Note that the concatenation operator is not + as in Java, and it does not overload any- 
thing else. If you forget this and add strings using +, they will be interpreted as numbers, 
with the result that ' one ' + ' two ' equals 0 (because no successful string-to-number conversion can 
be made). 



Concatenation and assignment 

Just as with arithmetic operators, PHP has a shorthand operator (. =) that combines concatenation 
with assignment. The following statement: 

$my_stri ng_var .= $new_addi ti on ; 

is exactly equivalent to: 

$my_stri ng_var = $my_stri ng_var . $new_addi ti on ; 

Note that, unlike commutative addition and multiplication, with this shorthand operator it matters 
that the new string is added to the right. If you want the new string tacked on to the left, there's no 
alternative shorter than: 

$my_stri ng„var = $new_addi ti on . $my_stri ng_var ; 

Note also that unassigned variables are treated as empty strings for the purposes of concatenation, 
so $my_stri ng_va r will end up unchanged if $new_addi ti on has never been given a value. 



The heredoc syntax 

In addition to the single-quote and double-quote syntaxes, PHP offers another way to specify a 
string, called the heredoc syntax. This syntax turns out to be extremely useful for specifying large 
chunks of variable-interpolated text, because it spares you from the need to escape internal quota- 
tion marks. It is especially useful in creating pages that contain HTML forms. 

The operator in the heredoc syntax is <<<. What is expected immediately after this is a label 
(unquoted) that indicates the beginning of a multiline string. PHP will continue including subse- 
quent lines in this string until it sees the same label again, beginning a line. The ending label may 
optionally be followed by a semicolon but by nothing else. 
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For example: 

$my_stri ng_va r = <<<E0T 

Everything in this rather unnecessarily wordy 

ramble of prose will be incorporated into the 

string that we are building up inevitably, inexorably, 

character by character, line by line, until we reach that 

blessed final line which is this one. 

EOT; 

Note that the preceding final EOT must not be indented at all — otherwise it will be taken to be just 
more text to be included. The label need not be literally EOT — it can be whatever you like within 
the normal rules for variable names in PHP. 

Interpolation of variables happens exactly the same way as with double-quoted strings. The nice 
thing about heredoc, though, is that quote signs can be included without any escaping and without 
prematurely terminating the string. Here's another example: 

echo <<<END0FF0RM 

<F0RM METH0D=P0ST ACTI0N=" { $_ENV[ ' PHP_SELF ' ] } "> 
<I NPUT TYPE=TEXT N AM E= F I RSTNAME VALUE=$f i rstname> 
<INPUT TY P E=SU BM I T NAME=SUBMIT VALUE=SUBMIT> 
</F0RM> 
ENDOFFORM; 

This has the effect of echoing a very simple form to the browser. 



String Functions 



PHP gives you a huge variety of functions for the munching and crunching of strings. If you're ever 
tempted to roll your own function that reads strings character by character to produce a new string, 
pause for a moment to think whether the task might be common. If so, there is probably a built-in 
function that handles it. 

For more information on string functions see http://php.net/manual/en/ref.strings.php. 

In this section, we present the basic functions for inspecting, comparing, modifying, and printing 
strings. If you want to be really comfortable with string manipulation in PHP, you should probably 
have at least a passing acquaintance with everything in this section. Both the regular expression 
functions and the more abstruse string functions can be found in Chapter 22. 

A note for C programmers: Many of the PHP string function names should be familiar to 
you. Just keep in mind that, because PHP takes care of memory management for you, the 
functions that return strings are allocating the string storage on their own and do not need to be given 
a preallocated string to write into. 
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Inspecting strings 



What kinds of questions can you ask strings? First on the list is how long the string is, using the 
s t r 1 e n ( ) function (the name is short for string length). 

$short_stri ng = "This string has 29 characters"; 
print( "It does have " . strl en ( $short_stri ng ) . 
" characters"); 



This code gives the following output: 

It does have 29 characters 



Knowing the string's length is particularly useful in form validation or for situations in which we'd 
like to loop through a string character by character. A useless but illustrative example, using the pre- 
ceding example string, is: 

for ($index = 0; $index < strl en ( $short_stri ng ) ; $index++) 
pri nt ( $short_st r i ng j $ i ndex } ) ; 

This simply prints: 

This string has 29 characters 

which is the string we started with. 



Finding characters and substrings 

The next question you can ask your strings is what they contain. For example, the s t r p o s ( ) func- 
tion finds the numerical position of a particular character in a string, if it exists. 

$twister = "Peter Piper picked a peck of pickled peppers"; 
pri nt ( " Locati on of 'p' is " . strpos ( $twi ster , 'p') .'<BR>'); 
pri nt ( " Locati on of 'q' is " . strpos ( $twi ster , 'q') .'<BR>'); 

This gives us the browser output: 

Location of 'p' is 8 
Location of 'q' is 



The ' q ' location is apparently blank because s t r p o s ( ) returns false if the character in question 
cannot be found, and a false value prints as the empty string. You should note that the s t rpos ( ) 
function is case sensitive. 



CAUTION 



The s t r p o s ( ) function is one of those cases where PH P's type-looseness can be prob- 
lematic. If no match can be found, the function returns a false value; if the very first 
character is a match, the function returns 0 (because the indexing count starts with 0 rather than 1). 
Both of these values look false if used in a Boolean test. One way to distinguish them is to use the iden- 
tity comparison operator (===, introduced as of PHP4), which is true only if its arguments are the same 
and of the same type — you can use it to test if the returned value is 0 (or is FA LS E) without risk of 
confusion with other values that might be the same after type coercion. 
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The strpos ( ) function can also be used to search for a substring rather than a single character, 
simply by giving it a multicharacter string rather than a single-character string. You can also supply 
an extra integer argument specifying the position to begin searching forward from. 

Searching in reverse is also possible, using the s t r r p o s ( ) function. (Note the extra r , which you 
can think of as standing for reverse.) This function takes a string to search and a single-character 
string to locate, and it returns the last position of occurrence of the second argument in the first 
argument. (Unlike with s t r p o s ( ) , the string searched for must have only one character.) If we use 
this function on our example sentence, we find a different position: 

$twister = "Peter Piper picked a peck of pickled peppers"; 

pri ntf ( " Locati on of 'p' is " . strrpos ( $twi ster , 'p') .'<BR>'); 

Specifically, we find the third p in peppers: 
Location of ' p' is 40 



Are strings immutable? 

In some programming languages (such as C), it is common to manipulate strings by directly changing 
them — that is, storing new characters into the middle of an existing string, replacing old characters. Other 
languages try to keep the programmer out of certain kinds of trouble by making string classes that are immutable 
(or unchangeable) — you can make new strings by creating modified copies of old ones, but once you have 
made a string, you are not allowed to change it by directly changing the characters that make it up. 

Where does PHP fit in? As it turns out, PHP strings can be changed, but the most common practice seems to 
be to treat strings as immutable. 

Strings can be changed by treating them as character arrays and assigning directly into them, like this: 

$my_string = "abcdefg"; 
$my_stri ng[5] = "X" ; 

pri nt( $my_stri ng . "<BR>"); 

which will give the browser output: 

abcdeXg 

This modification method seems to be undocumented, however, and shows up nowhere in the online manual, 
even though the corresponding extraction method (now updated to use curly braces) is highlighted. Also, almost 
all PHP string-manipulation functions return modified copies of their string arguments rather than making direct 
changes, which seems to indicate that this is the style that the PHP designers prefer. Our advice is not to use 
this direct-modification method to change strings, unless you know what you are doing and there is some large 
benefit in terms of memory savings. 
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Comparison and searching 



Is this string the same as that string? It's a question that your code is likely to have to answer fre- 
quently, especially when dealing with input typed by the end user. 



NOTE 



For the == operator, two strings are the same if they contain exactly the same sequence 
of characters. It does not test any stricter notion of being the same, such as being stored 
at the same memory address, but it does pay attention to case (or capitalization). 



The simplest method to find an answer is to use the basic comparison operator (==), which does 
equality testing on strings as well as numbers. 



CAUTION 



Comparing two strings using == (or the corresponding < and > operators) is trustworthy 
if both the arguments are strings and if you know that no type conversion is being per- 
formed. (See Chapter 4 for more on this.) Using strcmp( ) (described next) is always trustworthy. 



The most basic workhorse string- comparison function is s t r cmp ( ) . It takes two strings as argu- 
ments and compares them byte by byte until it finds a difference. It returns a negative number if the 
first string is less than the second and a positive number if the second string is less. It returns 0 if 
they are identical. 

The strcasecmp( ) function works the same way, except that the equality comparison is case 
insensitive . The function call s t r c a s e c m p ( " h e y ! " , "HEY!") should return 0 . 



Searching 

The comparison functions just described tell you whether one string is equal to another. To find 
out if one string is contained within another, use the s t r p o s ( ) function (covered earlier) or the 
s t r s t r ( ) function (or one of its relatives). 

The s t r s t r ( ) function takes a string to search in and a string to look for (in that order). If it suc- 
ceeds, it returns the portion of the string that starts with (and includes) the first instance of the 
string it is looking for. If the string is not found, a false value is returned. Here is a successful search 
followed by an unsuccessful search: 

$stri ng_to_search = " showsuponceshowsuptwi ce " ; 
$stri ng_to_f i nd = "up"; 

print ( "Result of looking for $stri ng_to„f i nd" . 

strstr( $stri ng_to_sea rch , $stri ng_to__f i nd ) . "<br>"); 
$stri ng_to_f i nd = "down"; 

pri nt ( " Resul t of looking for $ s t r i ng_to_f i nd" . 

strstr($string_to_search, $string_to_find)) ; 



which gives us: 



Result of looking for up: uponceshowsuptwi ce 
Result of looking for down: 



120 



Learning PHP String Handling 



The blank space after the colon in the second line is the result of trying to print a false value, which 
prints as the empty string. The s t r s t r ( ) function also has an alias by the name of s t r c h r ( ) . 
Other than the name, the two functions are identical. Just as with s t r cmp ( ), s t r s t r ( ) has a case- 
insensitive version, by the name of s t r 1 s t r ( ) . (That i in the middle stands for insensitive) It is 
identical to s t r s t r ( ) in every way, except that the comparison treats lowercase letters as indistin- 
guishable from their uppercase counterparts. The string functions we have covered so far are sum- 
marized in Table 7-1. 



TABLE 7-1 



Simple Inspection, Comparison, and Searching Functions 


Function 


Behavior 


strl en ( ) 


Takes a single string argument and returns its length as an integer. 


strpos ( ) 


Takes two string arguments: a string to search, and the string being searched for. 
Returns the (0-based) position of the beginning of the first instance of the string if 
found and a false value otherwise. It also takes a third optional integer argument, 
specifying the position at which the search should begin. 


strrpos ( ) 


Like strpos ( ), except that it searches backward from the end of the string, rather 
than forward from the beginning. The search string must only be one character long, 
and there is no optional position argument. 


strcmp( ) 


Takes two strings as arguments and returns 0 if the strings are exactly equivalent. If 
st rcmp ( ) encounters a difference, it returns a negative number if the first different 
byte is a smaller ASCII value in the first string, and a positive number if the smaller 
byte is found in the second string. 


strcasecmp( ) Identical to s t rcmp ( ), except that lowercase and uppercase versions of the same 
letter compare as equal. 


strstrC ) 


Searches its first string argument to see if its second string argument is contained in it. 
Returns the substring of the first string that starts with the first instance of the second 
argument, if any is found — otherwise, it returns false. 


strchr( ) 


Identical to strstrC ). 


stri str( ) 


Identical to s t r s t r ( ) except that the comparison is case independent. 



Substring selection 

Many of PHP's string functions have to do with slicing and dicing your strings. By slicing, we mean 
choosing a portion of a string; by dicing, we mean selectively modifying a string. Keep in mind that 
(most of the time) even dicing functions do not change the string you started out with. Usually, such 
functions return a modified copy, leaving the original argument intact. 
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The most basic way to choose a portion of a string is the s u b s t r ( ) function, which returns a new 
string that is a subsequence of the old one. As arguments, it takes a string (that the substring will be 
selected from), an integer (the position at which the desired substring starts), and an optional third 
integer argument that is the length of the desired substring. If no third argument is given, the sub- 
string is assumed to continue until the end. (Remember that, as with all PHP arguments that deal 
with numerical string positions, the numbering starts with 0 rather than 1.) 

For example, the statement: 

echo( substr( "Take what you need, and leave the rest behind", 
23)); 

prints the string leave the rest behind, whereas the statement: 

echo( substr( "Take what you need, and leave the rest behind", 
5, 13)); 

prints what you need — a 13-character string starting at (0-based) position 5. 

Both the start-position argument and the length argument can be negative, and in each case the neg- 
ativity has a different meaning. If the start position is negative, it means that the starting character 
is determined by counting backward from the end of the string, rather than forward from the begin- 
ning. (A start position of -1 means start with the last character, -2 means second to last, and so on.) 

Now, you might expect that a negative length would similarly imply that the substring should be 
determined by counting backward from the start character rather than forward. This is not the case 
— it is always true that the character at the start position is the first character in the returned string 
(not the last). Instead, a negative-length argument means that the final character is determined by 
counting backward from the end rather than forward from the start position. 

Here are some examples, with positive and negative arguments: 
$al phabet_test = " abcdef ghi j kl mnop" ; 



pri 


nt( 


'3: " . 


substr( Sal phabet_test , 3) . "< 


JR>" ) ; 




pri 


nt( 


'-3: " 


substr( $al phabet_test , -3) . 


<BR>" 


) ; 


pri 


nt( 


'3, 5: 


. substr( $al phabet_test , 3, 5 


. "< 


BR> " ) ; 


pri 


nt( 


'3, -5: 


" . substr( $al phabet_test , 3, 


5) . 


"<BR>") ; 


pri 


nt( 


'-3, -5 


" . substr( $al phabet_test , -3 


-5) 


. "<BR>") 


pri 


nt( 


'-3, 5: 


" . substr( $al phabet_test , -3, 


5) . 


"<BR>") ; 



This gives us the output: 

3: def ghi j kl mnop 

-3: nop 

3, 5: defgh 

3, -5: defghijk 

-3, -5: 

-3 , 5 : nop 
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Notice that there is an intimate relationship between the functions substrO, strstr(), and 
s t r p o s ( ) . The s u b s t r ( ) function selects a substring by numerical position, s t r s t r ( ) selects 
a substring by its content, and s t r p o s ( ) finds the numerical position of a given substring. In the 
case where we're sure in advance that the string Scontaining has the string $contained as a sub- 
string, the expression: 

strstrC $contai ni ng , Icontained) 

should be equivalent to the code: 

substr( $contai ni ng , strpos ( $conta i n i ng , $contained)) 



String cleanup functions 



Although they are technically substring functions, just like the others in this chapter, the functions 
chop( ), ltrim( ), and t r i m ( ) are really used for cleaning up untidy strings. They trim whitespace 
off the end, the beginning, and the beginning and end, respectively, of their single string argument. 
Some examples: 



$ o r i g i n a 1 
$chopped = 
$1 trimmed 
$trimmed = 
pri nt( "The 
pri nt ( 
pri nt( 
pri nt( 
pri nt( 
pri nt( 
pri nt ( 
pri nt ( 



Its 
The 
Its 
The 
Its 
The 
Its 



= " More than 
chop($origina 
= ltrim($origi 
trim($origina 
original is ' 
length is " . 
chopped versi 
length is " . 
Itrimmed vers 
length is " . 
trimmed versi 
length is " . 



meets the eye " ; 
1 ) ; 
nal ) ; 
1 ) ; 

$ori gi nal' <BR>" ) ; 

strlen($original) . "<BR>' 
on is ' $chopped ' <BR>" ) ; 

strl en( $chopped) . "<BR>": 
ion is ' $1 trimmed ' <BR>" ) ; 

strlen($ltrimmed) . "<BR>' 
on is ' $1 trimmed ' <BR>" ) ; 

strl en($trimmed) . "<BR>": 



The result 


as viewed by a browser is: 








The 


original is ' More 


than meets 


the eye ' 




Its 


length is 28 








The 


chopped version is 


' More than 


meets the 


eye 


Its 


length is 25 








The 


Itrimmed version is 


'More than 


meets the 


eye 


Its 


length is 26 








The 


trimmed version is 


'More than 


meets the 


eye ' 


Its 


length is 23 









The original string had three spaces at the end (subject to removal by c h o p ( ) or t r i m ( ) ) and two 
at the beginning (removed by 1 1 r i m ( ) and t r i m ( ) ). We were careful to describe our result as 
viewed by a browser because the multiple spaces have apparently been collapsed to one in the out- 
put, as browsers will do. If we viewed the HTML source produced by PHP originally, we would still 
see sequences of two and three spaces. 
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In addition to spaces, these functions remove whitespace like that denoted by the escape sequences 
\n, \ r, \t, and \0 (end-of-line characters, tabs, and the null character used to terminate strings in 
C programs). 

You will hear the name chop ( ) more frequently, but the identical function can also be called with 
the more logical name of r t r i m ( ) . Finally, notice that although c h o p ( ) sounds extremely destruc- 
tive, it does not harm the $ori gi nal argument, which retains the same value. 

String replacement 

The substring functions we've seen so far are all about choosing a portion of the argu- 
ment rather than building a genuinely new string. Enter the functions str_replace() and 
substr_repl ace( ). 

The str_repl ace ( ) function enables you to replace all instances of a particular substring with an 
alternate string. It takes three arguments: the string to be searched for, the string to replace it with 
when it is found, and the string to perform the replacement on. For example: 

$f i rst_edi ti on = 

"Burma is similar to Rhodesia in at least one way."; 
$second_edi ti on = str_repl ace (" Rhodes i a " , "Zimbabwe", 

$f i rst_edi ti on ) ; 
$thi rd_edi ti on = str_repl ace( "Burma" , "Myanmar", 

$second_edi ti on ) ; 

pri nt( $thi rd_edi ti on ) ; 
gives us: 

Myanmar is similar to Zimbabwe in at least one way. 

This replacement will happen for all instances found of the search string. If our outdated encyclope- 
dia could be snarfed into a single PHP string, we could update it in one pass. 

One subtlety to be aware of: What happens when multiple instances of the search string overlap? 
For example, with code like: 

$tri cky„stri ng = "ABA is part of ABABA"; 

$maybe_tri eked = str_repl ace( "ABA" , "DEF", $tri cky_stri ng ) ; 
pri nt ( " Substi tuti on result is ' $maybe_tri eked ' <BR>" ) ; 

the behavior we see is: 

Substitution result is 'DEF is part of DEFBA' 

which is probably as reasonable as any other alternative. 

As you've seen, str_repl ace ( ) picks out portions to replace by matching to a target string; by 
contrast, subst r_repl ace ( ) chooses a portion to replace by its absolute position. The function 
takes up to four arguments: the string to perform the replacement on, the string to replace it with, 
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the starting position for the replacement, and (optionally) the length of the section to be replaced. 
For example: 

print(substr_replace("ABCDEFG", 2, 3)); 

gives us: 

AB-FG 

The C D E portion of the string has been replaced with the single - . Notice that you are allowed 
to replace a substring with a string of a different length. If the length argument is omitted, it is 
assumed that you want to replace the entire portion of the string after the start position. 

The substr_replace() function also takes negative arguments for starting position and length, 
which are treated exactly the same way as in the s u b s t r ( ) function (described in the earlier section 
"Substring selection"). It is important to remember with both str„repl ace and substr_repl ace 
that the original string remains unchanged by these operations. 

Finally, we have a couple more whimsical functions that produce new strings from old. The 
s t r r e v ( ) function simply returns a new string with the characters of its input in reverse order. The 
st r_repeat ( ) function takes a string argument and an integer argument and returns a string that 
is the appropriate number of copies of the string argument tacked together. For example: 

pri nt ( str_repeat (" cheers ", 3)); 
gives us: 

cheers cheers cheers 
for the end of this section at long last. 

The substring search and replacement functions are summarized in Table 7-2. 



TABLE 7-2 



Substring and String Replacement Functions 

Function Behavior 

substr( ) Returns a subsequence of its initial string argument, as specified by the second (position) 

argument and optional third (length) argument. The substring starts at the indicated 
position and continues for as many characters as specified by the length argument or until 
the end of the string, if there is no length argument. 

A negative position argument means that the start character is located by counting backward 
from the end, whereas a negative length argument means that the end of the substring is 
found by counting back from the end, rather than forward from the start position. 



continued 
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Substring and String Replacement Functions 


Function 


Behavior 


chopO, or 
rtrim() 


Returns its string argument with trailing (right-hand side) whitespace removed. Whitespace 
is a blank space, \n, \ r, \t, and \0. 


1 tr1m( ) 


Returns its string argument with leading (left-hand side) whitespace removed. 


T p i rn C ) 


Returns its string argument with both leading and trailing whitespace removed. 


Str_ 

repl ace ( ) 


Used to replace target substrings with another string. Takes three string arguments: a substring 
to search for, a string to replace it with, and the containing string. Returns a copy of the 
containing string with all instances of the first argument replaced by the second argument. 


Substr_ 
repl ace( ) 


Puts a string argument in place of a position-specified substring. Takes up to four 
arguments: the string to operate on, the string to replace with, the start position of the 
substring to replace, and the length of the string segment to be replaced. Returns a copy of 
the first argument with the replacement string put in place of the specified substring. 

If the length argument is omitted, the entire tail of the first string argument is replaced. 
Negative position and length arguments are treated as in substrt ). 



Case functions 

These functions change lowercase to uppercase and vice versa. The first two (de)capitalize entire 
strings, whereas the second two operate only on first letters of words. 

strtolower() 

The strtolowerO function returns an all-lowercase string. It doesn't matter if the original is all 
uppercase or mixed. This fragment: 

<?php 

$original = "They DON'T KnoW they're SHOUTING"; 
Slower = strtol ower( $ori gi nal ) ; 
echo Slower; 
?> 

returns the string "they don't know they're shouting". 

ri r, I If you have been faced with extensive form-validation needs before, you might already 

have noticed that st r to! ower () is extremely handy for use with those that still think 
their e-mail addresses contain capital letters. Subsequent functions in this category will prove similarly 
useful. 
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strtoupperO 

The strtoupper( ) function returns an all-uppercase string, regardless of whether the original was 
all lowercase or mixed: 

<?php 

$original = "make this link stand out"; 
echo("<B>strtoupper($original )</B>") ; 
?> 



ucfirstO 

The ucfirstO function capitalizes only the first letter of a string: 
<?php 

$original = "polish is a word for which pronunciation depends on 

capitalization"; 

echo(ucfirst($original )); 

?> 



ucwordsO 

The u c w o r d s ( ) function capitalizes the first letter of each word in a string: 
<?php 

$original = "truth or consequences"; 
$capitalized = ucwords ( $ori gi nal ) ; 

echo "While loriginal is a parlor game, $capitalized is a town in New 

Mexi co . " ; 

?> 



j j Cj'J~F~~' [ Neither ucwords ( ) nor ucfirstO converts anything into lowercase. Each makes only 
" Ihe appropriate leading letters into uppercase. If there are inappropriate capital letters in 

the middle of words, they will not be corrected. 



Escaping functions 

One of the virtues of PHP is that it is willing to talk to almost anybody. In its role as a glue language 
PHP talks to database servers, to LDAP servers, over sockets, and over the HTTP connection itself. 
Frequently, it accomplishes this communication by first constructing a message string (like a data- 
base query) and then shipping it off to the receiving program. Often, however, the program attaches 
special meanings to certain characters, which therefore have to be escaped, meaning that the receiv- 
ing program is told to take them as a literal part of the string rather than treating them specially. 

Many users deal with this issue by enabling magic-quotes, which ensures that quotation marks 
are escaped before strings are inserted into databases. If that's not feasible or desirable, there 
are good old-fashioned strip-slashing and add-slashing by hand. The addslashesO function 
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escapes quotation marks, double quotation marks, backslashes, and NULLs with backslashes, 
because these are the characters that typically need to be escaped for database queries. 

<?php 

$escapedstri ng = addsl ashes( "He said, 'I'm a dog.'"); 

$query = "INSERT INTO test (quote) values ( ' $escapedstri ng ' ) " ; 

$result = mysql_query ( Iquery ) or di e(mysql_error( ) ) ; 

?> 

This will prevent the SQL statement from thinking it's finished right before the letter I . When you 
pull the data back out, you'll need to use s t r i p s 1 a s h e s ( ) to get rid of the slashes. 

<?php 

$query = "SELECT quote FROM test WHERE ID=1"; 
$result = mysql_query ( Iquery ) or di e(mysql_error( ) ) ; 
$new_row = my sql_f etch_ar ray ( $ resul t ) ; 
$quote = stri psl ashes ( $new_row[0] ) ; 



echo $quote; 



The quotemeta ( ) function escapes a wider variety of characters, all of which usually have a special 
meaning in the Unix command line: ' . ' , ' \ 1 ' + ','*', '?','[',' A ', ']','(', '$', and ' ) ' . 
For example, the code: 

$ 1 i t e r a 1 _s t r i n g = 

'These characters ($, *) are very special to me\n<BR>'; 
$qm_string = quotemeta ( $1 i teral_stri ng ) ; 
echo $qm_string; 

will print: 

These characters \(\$, \*\) are very special to rneWn 

- rj r "rj'.'rV For escaping functions specific to HTML, see the "Advanced String Functions" section in 
\i\ rrWrn* chapter 22. 



Printing and output 

The workhorse constructs for printing and output are print and echo, which we cover in detail in 
Chapter 4. The standard way to print the value of variables to output is to include them in a doubly 
quoted string (which will interpolate their values) and then give that string to print or echo. 

If you need even more tightly formatted output, PHP also offers p r i n t f ( ) and s p r i n t f ( ) , which 
are modeled on C functions of the same name. The two functions take identical arguments: a special 
format string (described later in this section) and then any number of other arguments, which will 
be spliced into the right places in the format string to make the result. 

The only difference between p r 1 n t f ( ) and s p r 1 n t f ( ) is that p r i n t f ( ) sends the resulting string 
directly to output, whereas spri ntf ( ) returns the result string as its value. 
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To C programmers: This spri ntf ( ) function is slightly different from C's version in that 
you need not supply an allocated string for s p r i n t f ( ) to write into — PHP allocates the 



result string for you. 

The complicated bit about these functions is the format string. Every character that you put in the 
string will show up literally in the result, except the % character and characters that immediately 
follow it. The % character signals the beginning of a conversion specification, which indicates how to 
print one of the arguments that follow the format string. 

After the %, there are six elements that make up the conversion specification, some of which are 
optional: padding, alignment, minimum width, precision, and type. 

■ An optional sign character used for numbers to indicate whether the number will be 
negative (-). 

■ The single (optional) padding character is either a 0 or a space ( ). This character is used to 
fill any space that would otherwise be unused but that you have insisted (with the mini- 
mum width argument) be filled with something. If this padding character is not given, the 
default is to pad with spaces. 

■ The optional alignment character (- ) indicates whether the printed value should be left- or 
right-justified. If present, the value will be left-justified; if absent, it will be right-justified. 

■ An optional minimum width number that indicates how many spaces this value should take 
up, at a minimum. (If more spaces are needed to print the value, it will overflow beyond its 
bounds.) 

■ An optional precision specifier is written as a dot (. ) followed by a number. It indicates 
how many decimal points of precision a double should print with. (This has no effect on 
printing things other than doubles.) 

■ A single character indicating how the type of the value should be interpreted. The f char- 
acter indicates printing as a double, the s character indicates printing as a string, and then 
the rest of the possible characters (b, c, d, o, x, X) mean that the value should be inter- 
preted as an integer and printed in various formats. Those formats are b for binary, c for 
printing the character with the corresponding ASCII values, o for octal, x for hexadecimal 
(with lowercase letters) and X for hexadecimal with uppercase letters. 

Here's an example of printing the same double in several different ways: 

<pre> 
<?php 

$value = 3.14159; 

printf ( "%f , %10f ,%-010f ,%2.2f\n" , 

lvalue, lvalue, lvalue, lvalue); 

?> 

</pre> 
gives us: 

3.141590, 3.141590,3.141590000000000, 3.14 
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The <pre></pre> construct is HTML that tells the browser to format the enclosed block literally, 
without collapsing many spaces into one, and so on. 



Summary 

Strings are sequences of characters, and the string is one of the eight basic data types in PHP. Unlike 
in some other languages, there is no distinct character type, since single characters behave as strings 
of length 1. Literal strings are specified in code by either single (' ) or double (") quotation marks. 
Singly quoted strings are interpreted nearly literally, while doubly quoted strings interpret a number 
of escape sequences and automatically interpolate variable values. 

The main string operator is ' . ' , which concatenates two strings together. In addition, there is a 
dizzying array of string functions, which help you inspect, compare, search, extract, chop, replace, 
slice, and dice strings to your heart's content. For the most sophisticated string-manipulation needs, 
PHP supports both POSIX and Perl-compatible regular expressions (covered in Chapter 22). 



130 




Qli'.plsriX' 5 



Learning Arrays 



Arrays are definitely one of the coolest and most flexible features of 
PHP. Unlike vector arrays from other languages (C, C++, Pascal), 
PHP arrays can store data of varied types and automatically orga- 
nize it for you in a large variety of ways. 



CROSS-REF 



This chapter treats arrays and array functions in some depth. 
For a very quick introduction to the syntax and use of arrays, 
see Chapter 4. For a more complete survey of advanced array functions, see 
Chapter 21. 



IN THIS CHAPTER 



An all-purpose data type 
Storing and retrieving values 
Multidimensional arrays 



Iteration 



The Uses of Arrays 



An array is a collection of variables indexed and bundled into a single, eas- 
ily referenced supervariable that offers an easy way to pass multiple values 
between lines of code, functions, and even pages. Throughout much of this 
chapter, we will be looking at the inner workings of arrays and exploring 
all the built-in PHP functions that manipulate them. Before we get too deep 
into that, however, it's worth listing the common ways that arrays are used 
in real PHP code. 

Many built-in PHP environment variables are in the form of arrays (for 
example, $„SESSI0N, which contains all the variable names and values 
being propagated from page to page via PHP's session mechanism). If you 
want access to them, you need to understand, at a minimum, how to refer- 
ence arrays. 

Almost any situation that calls for a number of pieces of data to be pack- 
aged and handled as one is appropriate for a PHP array. 
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What Are PHP Arrays? 



PHP arrays are associative arrays with a little extra machinery thrown in. The associative part means 
that arrays store element values in association with key values rather than in a strict linear index 
order. (If you have seen arrays in other programming languages, they are likely to have been vector 
arrays rather than associative arrays — see the related sidebar for an explanation of the difference.) 
If you store an element in an array, in association with a key, all you need to retrieve it later from 
that array is the key value. For example, storage is as simple as this: 

$state_l ocati on[ ' San Mateo'] = 'California'; 

which stores the element 'California' in the array variable $state_location,in association 
with the lookup key 'San Mateo'. After this has been stored, you can look up the stored value by 
using the key, like so: 

$state = $state_l ocati on [' San Mateo']; // equals 'California' 
Simple, no? 

If all you want arrays for is to store key/value pairs, the preceding information is all you need to 
know. Similarly, if you want to associate a numerical ordering with a bunch of values, all you have to 
do is use integers as your key values, as in: 

$my_array[l] = "The first thing"; 

$my_array [2] = "The second thing"; // and so on ... 



NOTE 



For Perl programmers: Arrays in PHP are much like hashes in Perl, with some syntactic 
differences. For one thing, all variables in PHP are denoted with a leading $, not just sca- 
lar variables. Second, even though the array is associative, the indices are grouped by square brackets 
([ ]) rather than curly braces (( )). Finally, there is no array or list type indexed only by integers. The 
convention is to use integers as associative indices, and the array itself maintains an internal ordering 
for iteration purposes. 

In addition to the machinery that makes this kind of key/value association possible, arrays track 
some other things behind the scenes. Because of this, we sometimes treat them as other kinds of 
data structures. As you will see, arrays can be multidimensional. They can store values in associa- 
tion with a sequence of key values rather than a single key. Also, arrays automatically maintain an 
ordered list of the elements that have been inserted in them, independent of what the key values 
happen to be. This makes it possible to treat arrays as linked lists. In general, we will reveal the 
workings of this extra machinery as we explore the functions that use it. 



NOTE 



A note for C++ programmers: You should be aware that arrays can handle some of the 
same tasks that require the use of template libraries in C++. Much of the reason for hav- 
ing templates in the first place is to get around restrictions having to do with strict typing of data. PHP's 
looser typing system makes it possible, for example, to write general algorithms that iterate over the 
contents of arrays without committing to the type of the array elements themselves. 
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Associative Arrays versus Vector Arrays 

If you have programmed in languages like C, C++, and Pascal, you are probably used to a particular usage 
of the word array, one that doesn't match the PHP usage very well at all. A more specific term for a C-style 
array is a vector array, whereas a PHP-style array is an associative array. 

In a vector array, the contained elements all need to be of the same type, and usually the language compiler 
needs to know in advance how many such elements there are likely to be. For example, In C you might declare 
an array of 100 double-precision floating-point numbers with a statement like: 

double my_array[100] ; // This is C, not PHP! 

The restriction on types and the advance declaration of size have an associated benefit: Vector arrays are very 
fast, both for storage and lookup. The reason is that the compiler will usually lay out the array in a contiguous 
block of computer memory, as large as the size of the element type multiplied by the number of elements. 
This makes it very easy for the programming language to locate a particular array slot — all it needs to know 
is the starting memory address of the array, the size of the element type, and the index of the element it wants 
to look up, and it can directly compute the memory address of that slot. 

By contrast, PHP arrays are associative (and so some would call them hashes, rather than arrays). Rather than 
having a fixed number of slots, PHP creates array slots as new elements that are added to the array. Rather 
than requiring elements to be of the same type, PHP arrays have the same type-looseness that PHP variables 
have — you can assign arbitrary PHP values to be array elements. Finally, because vector arrays are all about 
laying out their elements in numerical order; the keys used for lookup and storage must be integer numbers. 
PHP arrays can have keys of arbitrary type, instead, including string keys. So, you could have successive array 
assignments like: 

$my_a rray [ 1 ] = 1; 
$my_array[ ' orange ' ] = 2; 
$my_array[3] = 3; 

without any paradox. The result is that your array has three values (1, 2, 3), each of which is stored in associa- 
tion with a key (1, 'orange ' , and 3, respectively). 

The extra flexibility of associative arrays comes at a price, because there is a little bit more going on between 
your code and the actual computation of a memory address than is true with vector arrays. For most web 
programming purposes, however, this extra access time is not a significant cost. 

The fact that integers are legal keys for PHP arrays means that you can easily imitate the behavior of a vector 
array, simply by restricting your code to use only integers as keys. 



r'rr r*~. ' \ A general note for programmers familiar with other languages: PHP does not need very 
ta«n^^^~ many different kinds of data structures, in part because of the great flexibility offered by 
PHP arrays. By careful choice of a subset of array functions, you can make arrays pretend to act like 
vector arrays, structure/record types, linked lists, hash tables, or stacks and queues — data structures 
that in other languages either require their own data types or less common language features such as 
pointers and explicit memory management. 
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Creating Arrays 

There are three main ways to create an array in a PHP script: by assigning a value into one (and 
thereby implicitly creating it), by using the a r ray ( ) construct, and by calling a function that hap- 
pens to return an array as its value. 



Direct assignment 

The simplest way to create an array is to act as though a variable is already an array and assign a 
value into it, like this: 

$my_array[l] = "The first thing in my array that I just made"; 

If $my_a r ray was an unbound variable (or bound to a nonarray variable) before this statement, it 
will now be a variable bound to an array with one element. If instead $my_a rray was already an 
array, the string will be stored in association with the integer key 1 . If no value was associated with 
that number before, a new array slot will be created to hold it; if a value was associated with 1, the 
previous value will be overwritten. (You can also assign into an array by omitting the index entirely 
as in $ my _a r r a y [ ] , described later in this chapter.) 



The arrayO construct 



The other way to create an array is via the a r ray ( ) construct, which creates a new array from the 
specification of its elements and associated keys. In its simplest version, a r ray ( ) is called with no 
arguments, which creates a new empty array. In its next simplest version, a r ray ( ) takes a comma- 
separated list of elements to be stored, without any specification of keys. The result is that the ele- 
ments are stored in the array in the order specified and are assigned integer keys beginning with 
zero. For example, the statement: 

$f rui t_basket = array (' appl e ' , 'orange', 'banana', 'pear'); 

causes the variable $ f r u i t_b a s k e t to be assigned to an array with four string elements ('apple', 
'banana', 'orange', 'pear'), with the indices 0 , 1 , 2 , and 3 , respectively. In addition (as you'll 
see in the "Iteration" section later in this chapter), the array will remember the order in which the 
elements were stored. 

The assignment to $f rui t_bas ket, then, has exactly the same effect as the following: 

$f rui t_basket[0] = 'apple'; 

$f rui t_basket[l] = 'orange'; 

$f rui t_basket[2] = 'banana'; 

$f rui t_basket[3] = 'pear'; 

assuming that the $fruit_basket variable was unbound at the first assignment. The same effect 
could also have been accomplished by omitting the indices in the assignment, like so: 

$f rui t_bas ket [ ] = 'apple'; 
$f rui t„bas ket [ ] = 'orange'; 
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$f ruit_basket[] = 'banana'; 
$f ruit_basket[] = 'pear'; 

In this case, PHP again assumes that you are adding sequential elements that should have numerical 
indices counting upward from zero. 



Yes, the default numbering for array indices starts at zero, not one. This is the conven- 
tion for arrays in most programming languages. We're not sure why computer scientists 
start counting at zero (mathematicians, like everyone else in the world, start with one), but it prob- 
ably has its origin in the kind of pointer arithmetic that calculates memory addresses for vector arrays. 
Addresses for successive elements of such arrays are found by adding successively larger offsets to the 
array's address, but the offset for the first element is zero (because the first element's address is the 
same as the array's address). 



Specifying indices using arrayO 



The simple example of a r r ay ( ) in the preceding section assigns indices to our elements, but those 
indices will be the integers, counting upward from zero — we're not getting a lot of choice in the 
matter. As it turns out, a r r ay ( ) offers us a special syntax for specifying what the indices should be. 
Instead of element values separated by commas, you supply key/value pairs separated by commas, 
where the key and value are separated by the special symbol =>. 

Consider the following statement: 

$f ruit_basket = array(0 => 'apple', 1 => 'orange', 

2 => 'banana', 3 => 'pear'); 

Evaluating it will have exactly the same effect as our earlier version — each string will be stored in 
the array in succession, with the indices 0, 1, 2, 3 in order. Instead, however, we can use exactly the 
same syntax to store these elements with different indices: 

$f ruit_basket = array('red' => 'apple', 'orange' => 'orange', 

'yellow' => 'banana', 'green' => 'pear'); 

This gives us the same four elements, added to our new array in the same order, but indexed by 
color names rather than numbers. To recover the name of the yellow fruit, for example, we just 
evaluate the expression: 

$f ruit_basket[ 'yel 1 ow' ] // will be equal to 'banana' 

Finally, as we said earlier, you can create an empty array by calling the array function with no 
arguments. For example: 

$my_empty_array = array(); 

creates an array with no elements. This can be handy for passing to a function that expects an array 
as argument. 
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Functions returning arrays 

The final way to create an array in a script is to call a function that returns an array. This may be a user- 
defined function, or it may be a built-in function that makes an array via methods internal to PHP. 

Many database-interaction functions, for example, return their results in arrays that the functions 
create on the fly. Other functions exist simply to create arrays that are handy to have as grist for later 
array-manipulating functions. One such is range () , which takes two integers as arguments and 
returns an array filled with all the integers (inclusive) between the arguments. In other words: 

$my_array = ranged, 5); 

is equivalent to: 

$my_array = arrayd, 2, 3, 4, 5); 



Retrieving Values 

After we have stored some values in an array, how do we get them out again? 

Retrieving by index 

The most direct way to retrieve a value is to use its index. If we have stored a value in $my_array at 
index 5, $my_a r ray [ 5 ] should evaluate to the stored value. If $my_a r ray has never been assigned, 
or if nothing has been stored in it with an index of 5, $ my _a r r a y [ 5 ] will behave like an unbound 
variable. 

The list() construct 

There are a number of other ways to recover values from arrays without using keys, most of which 
exploit the fact that arrays are silently recording the order in which elements are stored. We cover 
this in more detail in this chapter's "Iteration" section, but one such example is 1 i s t ( ) , which is 
used to assign several array elements to variables in succession. Suppose that the following two 
statements are executed: 

$f rui t_basket = array (' appl e ' , 'orange', 'banana'); 
1 i st( $red_f rui t , $orange„f rui t ) = $f rui t_basket ; 

This will assign the string 'apple' to the variable $red_f rui t and the string 'orange ' to the 
variable $orange_fruit (with no assignment of 'banana', because we didn't supply enough 
variables). The variables in 1 i s t ( ) will be assigned to elements of the array in the order they were 
originally stored in the array. Notice the unusual behavior here — the 1 i s t ( ) construct is on the 
left-hand side of the assignment operator (=), where we normally find only variables. 
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In some sense, 1 i st ( ) is the opposite or inverse of array ( ) because array ( ) packages its argu- 
ments into an array, and 1 i st ( ) takes the array apart again into individual variable assignments. If 
we evaluate: 

1 i st( $f i rst , $second) = array ( $fi rst , secord); 

the original values of $f i rst and Ssecond will be assigned to those variables again, after having 
been briefly stored in an array. 




We have been careful to refer to both a r r a y ( ) and 1 i s t ( ) as constructs, rather than 
functions. This is because they are not in fact functions — like certain other specialized 



PHP language features (i f, wh i 1 e, f uncti on, and so on) they are interpreted specially by the lan- 
guage itself and are not run through the usual routine of function-call interpretation. Remember that 
the arguments to a function call are evaluated before the function is really invoked on those arguments, 
so constructs that need to do other kinds of interpretation on what they are given cannot be imple- 
mented as function calls. It's a useful exercise to look hard at the example uses of both array ( ) and 
1 i st ( ) to figure out why treating them as function calls could not result in the behavior advertised. 



Multidimensional Arrays 

So far, the array examples we have looked at have all been one-dimensional, with only one level 
of bracketed keys. However, PHP can easily support multidimensional arrays, with arbitrary num- 
bers of keys. And just as with one-dimensional arrays, there is no need to declare our intentions in 
advance — the first reference to an array variable can be an assignment like: 

$mul ti_a rray [ 1 ] [2] [3] [4] [5] = "deeply buried treasure"; 

That is a five-dimensional array with successive keys that happen, in this case, to be five successive 
integers. 

Actually, in our opinion, thinking of arrays as multidimensional makes matters more confusing 
than they need to be. Instead, just remember that the values that are stored in arrays can themselves 
be arrays, just as legitimately as they can be strings or numbers. The multiple-index syntax in the 
preceding example is simply a concise way to refer to a (four-dimensional) array that is stored with 
a key ofl in $multi_array, which in turn has a (three-dimensional) array stored in it, and so on. 
Note also that you can have different depths of reference in different parts of the array, like this: 

$mul ti_l evel_array[0] = "a simple string"; 

$mul ti_l evel_array [1] [ ' contai ns ' ] = "a string stored deeper"; 

The integer key of 0 stores a string, and the key of 1 stores an array that, in turn, has a string in it. 
However, you cannot continue on with this assignment: 

$mul ti_l evel _a r ray [0] [ ' conta i ns ' ] = "another deep string"; 

without the result of losing the first assignment to 'a simple string'. The key of 0 can be used to 
store a string or another array, but not both at once. 
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If we remember that multidimensional arrays are simply arrays that have other arrays stored in 
them, it's easier to see how the array ( ) creation construct generalizes. In fact, even this seemingly 
complicated assignment is not that complicated: 

$cornucopia = a rray ( ' f rui t ' => 

array ( ' red ' => ' appl e ' , 

'orange ' => ' orange ' , 

' yel 1 ow ' => 'banana ' , 
' green ' => ' pea r ' ) , 
'flower' => 

array ( ' red ' => ' rose ' , 

'yellow' => 'sunflower', 

'purple' = > 'iris')); 



It is simply an array with two values stored in association with keys. Each of these values is an array 
itself. After we have made the array, we can reference it like this: 

$ ki nd_wanted = 'flower'; 
$col or_wanted = 'purple'; 

print("The $col or_wanted $ ki nd_wanted is " . 

$cornucopia[$ki nd_wanted] [ $col or__wanted] ) ; 



See the browser output: 

The purple flower is iris 



"FT? i"' I There's a reason that we used the string concatenation operator, . , in the preceding 
print statement, rather than simply embedding the $cornucopia[$ki nd_wanted] 
[ $ col or wanted ] in our print string as we do with other variables. PHP3 string parsing can be 
confused by multiple array indices within a double-quoted string, so it needs to be concatenated sepa- 
rately. PHP since version 4 handles this in a better way — you are safe embedding array references in a 
string as long as you enclose the reference in curly braces, like this: 

print( "The thing we want is 
{$cornucopia[$ki nd_wanted] [$col or_wanted] } " ) ; 



Finally, notice that there is no great penalty for misindexing into a multidimensional array when we 
are trying to retrieve something; if no such key is found, the expression is treated like an unbound 
variable. So, if we try the following instead: 

$kind_wanted = 'fruit'; 

$col or_wanted = 'purple'; //uh-oh, we didn't store any plums 
print("The $col or_wanted $kind_wanted is " . 

$cornucopia[$ki nd_wanted] [$col or_wanted] ) ; 

The worst that happens is the unsatisfying: 
The purple fruit is 
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This is the worst thing that happens, of course, unless you have raised your error_reporting level 
to E_ALL, as we advise you to do at some points in this book. In that case, you will get a notice mes- 
sage about an undefined index ('purple') just as you would if you had an unbound variable. 



Inspecting Arrays 

Now we can make arrays, store values in arrays, and then pull the values out again when we want 
them. Table 8-1 summarizes a few other functions we can use to ask questions of our arrays. 



TABLE 8-1 



Simple Functions for Inspecting Arrays 


Function 


Behavior 


i s_a rray ( ) 


Takes a single argument of any type and returns a true value if the argument 
is an array, and false otherwise. 


count ( ) 


Takes an array as argument and returns the number of nonempty elements 
in the array. (This will be 1 for strings and numbers.) 


s i z e o f ( ) 


Identical to count ( ). 


i n_a rray ( ) 


Takes two arguments: an element (that might be a value in an array), and 
an array (that might contain the element). Returns true if the element is 
contained as a value in the array, f al se otherwise. (Note that this does not 
test for the presence of keys in the array.) 


i sset ( $a rray [$key ] ) 


Takes an a rraylkey} form and returns true if the key portion is a 
valid key for the array. (This is a specific use of the more general function 
i s set ( ), which tests whether a variable is bound.) 



Note that all of these functions work on only the depth of the array specified, so that testing for val- 
ues layers deep in a multidimensional array requires that you specify out that number of places. In 
the case of our preceding $cornucopia example, for instance: 

count( $cornucopi a ) ; // what do you expect here? 2? 7? 9? 
returns a 2 , while 

count($cornucopia[fruit]) ; 
returns 4. 
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Deleting from Arrays 

Deleting an element from an array is simple, exactly analogous to getting rid of an assigned variable. 
Just call unset ( ) , as in the following: 

$my_array[0] = 'wanted'; 
$my_array[l] = 'unwanted'; 
$my_array [2] = 'wanted again'; 
unset ( $my_array[l] ) ; 

Assuming that $my_a r ray was unbound when we started, at the end it has two values ('wanted ' , 
'wanted again'), in association with two keys (0 and 2, respectively). It is as though we had 
skipped the original 'unwanted' assignment (except that the keys are numbered differently). 

Note that this is not the same as setting the contents to an empty value. If, instead of calling 
unset (), we had the following statement: 

$my_array [1] = ' ' ; 

at the end we would have three stored values ('wanted', ' ', 'wanted again') in association with 
three keys (0,1, and 2, respectively). 



Iteration 

We've seen how to put things into arrays, how to find them once we have put them there, and how 
to delete them when we don't want them anymore. What we need next is a technique for dealing 
with array elements in bulk. Iteration constructs help us do this by letting us step or loop through 
arrays, element by element or key by key. 

We'll first delve briefly into the internal representation of arrays to understand how PHP supports 
iteration. (Although important, this subsection is skippable — if you want to use it but don't want to 
know how it works, you can jump down to the section titled "Using iteration functions.") 

Support for iteration 

In addition to storing values in association with their keys, PHP arrays silently build an ordered 
list of the key/value pairs that are stored, in the order that they are stored. The reason for this is to 
support operations that iterate over the entire contents of an array. (Notice that this is difficult to 
do simply by building a loop that increments an index, because array indices are not necessarily 
numerical.) 

There is, in fact, sort of a hidden pointer system built into arrays. Each stored key/value pair points 
to the next one, and one side effect of adding the first element to an array is that a current pointer 
points to the very first element, where it will stay unless disturbed by one of the iteration functions. 
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l Each array remembers a particular stored key/value pair as being the current one, and 
™ array iteration functions work in part by shifting that current marker through the internal 
list of keys and values. Although we will call this marker the current pointer, PHP does not support full 
pointers in the sense that C and C++ programmers may be used to, and this usage of the word will turn 
up only in the context of iterating through arrays. 

This linked-list pointer system is an alternative way to inspect and manipulate arrays, which exists 
alongside the system that allows key-based lookup and storage. Figure 8-1 shows an abstract view 
(not necessarily reflecting the real implementation) of how these systems locate elements in an array. 



FIGURE 8-1 
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Using iteration functions 

To explore the iteration functions, let's construct a sample array that we can iterate over. 

$major_city_info = array(); 
$major„city_info[0] = 'Chicago'; 
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$major_ci ty_i nf o[ ' Chi cago ' ] = 'United States'; 

$ma j or_ci ty_i nf o [ 1 ] = 'Stockholm'; 

$ma j or_ci ty_i nf o [ ' Stockhol m ' ] = 'Sweden'; 

$ma jor_ci ty_i nfo[2] = 'Montreal'; 

$major_ci ty_i nfo[ ' Montreal ' ] = 'Canada'; 

In this example, we created an array and stored some names of cities in it, in association with 
numerical indices. We also stored the names of the relevant countries into the array, indexed by the 
city names. (We could have accomplished all this with one big call to a r r ay ( ) , but the separate 
statements make the structure of the array somewhat clearer.) 

Now, we can use the array key system to pull out the data we have stored. If we want to rely on the 
convention in the preceding example (cities stored with numerical indices, countries stored with 
city-name indices), we can write a function that prints the city and the associated country, like this: 

function ci ty_by_number ( $number_i ndex , $city_array) 
{ 

if ( I sSet ( $ci ty_a rray [$number_i ndex] ) ) 
I 

$the_city = $ci ty_array[$number_i ndex] ; 
$the_country = $ci ty_array [$the_ci ty] ; 
pri nt ( " $the_ci ty is in $the„country<BR>" ) ; 

) 

} 

ci ty_by_n umber ( 0 , $ma jor_ci ty_i nf o ) ; 
ci ty„by_n umber ( 1 , $ma jor_ci ty_i nf o ) ; 
ci ty_by_n umber ( 2 , $ma jor_ci ty_i nf o ) ; 

If we have set $ m a j o r_c i ty , as in the previous block of code, the browser output we should expect is: 

Chicago is in United States 
Stockholm is in Sweden 
Montreal is in Canada 

Now, this method of retrieval is fine when we know how the array is structured and we know what 
all the keys are, but what if you would simply like to print everything that an array contains? 

Our favorite iteration method: foreach 

Our favorite construct for looping through an array is foreach. Although it is probably inherited 
from Perl's foreach, it has a somewhat odd syntax (which is not the same as Perl's odd syntax). It 
comes in two flavors — which one you decide to use will depend on whether you care about the 
array's keys or just the values. 

foreach ( $array_vari abl e as $ va 1 ue_va ri abl e ) ( 

// .. do something with the value in $val ue_vari abl e 
) // Note that this is an example template, not real PHP code 
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foreach ($array_vari abl e as $key_var => $value_var) { 
// .. do something with $key_var and/or $value_var 
) 

Although in the preceding pseudocode we assume that the array of interest is in the variable 
$array_variable, you can have any expression that evaluates to an array in that position, for 
example: 

foreach ( f uncti on_return i ng_array ( ) as $ val ue_va ri abl e ) { 
// .. do something with the value in $val ue_vari abl e 

) 

r rTr r" ' ' F Like array ( ) and 1 i st( ), but unlike the genuine iteration functions in the rest of this 

section, foreach is a language construct, not a function. (See the earlier note about 
1 i st ( ) for an explanation of the difference.) 

As an example, let's write a function to print all the names from our sample array: 

function pri nt_al l_f oreach ( $ci ty_a rray ) 
( 

foreach ($city_array as $name_val ue ) ( 
pri nt ( " $name_val ue<BR> " ) ; 

} 

) 

pri nt_al l_f oreach ( $ma j or_ci ty_i nf o ) ; 

pri nt_al l_f oreach ( $maj or_ci ty_i nfo );/ / again, as an experiment 
As output, we get all the names, in the order we stored them, twice over: 

Chi cago 
United States 
Stockhol m 
Sweden 
Montreal 
Canada 
Chi cago 
United States 
Stockhol m 
Sweden 
Montreal 
Canada 

We printed the contents twice to show that calling the function is repeatable. 

Iterating with current() and next() 

We like foreach, but it is really only good for situations where you want to simply loop through an 
array's values. For more control, let's look at current( ) and next( ). 
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The c u r r e n t ( ) function returns the stored value that the current pointer points to. (Refer back to 
Figure 8-1 for a diagram of the array internals.) When an array is newly created with elements, the 
element pointed to will always be the first element. The next ( ) function first advances that pointer 
and then returns the current value pointed to. If the n ext ( ) function is called when the current 
pointer is already pointing to the last stored value and, therefore, runs off the end of the array, the 
function returns a false value. 

As an example, we can print out an array's contents with the iteration functions current ( ) and 
next ( ) . (Notice that the final function call is repeated.) 

function pri nt_al 1 _next ( $ci ty_a r r ay ) 

{ // warn i ng- -doesn ' t quite work. See the function each() 
$current__i tern = current ( $ci ty_a rray ) ; 
if ( $current_i tern) 

pri nt( "$current_i tem<BR>" ) ; 
else 

pri nt( "There ' s nothing to print"); 
whi 1 e( $current_i tern = next($city_array) ) 
pri nt ( " $current_i tem<BR> " ) ; 

} 

pri nt_al 1 _next ( $ma j or_ci ty_i nf o ) ; 

pri nt_al 1 _next ( $ma j or__ci ty_i nf o ) ; / / again, to see what happens 



There is a gotcha lurking in the preceding code example, which doesn't bite us in this 
particular example but makes this function untrustworthy as a general method for find- 
ing everything in an array. The problem is that we may have stored a false value in the array, which our 
while loop won't be able to distinguish from the false value that next ( ) returns when it has run out 
of array elements. See the discussion of the each ( ) function later in this chapter under "Empty values 
and the each ( ) function" for a solution. 

When we execute this array-printing code, we get the following again: 

Chicago 
United States 
Stockhol m 
Sweden 
Montreal 
Canada 
Chicago 
United States 
Stockhol m 
Sweden 
Montreal 
Canada 

Now, how is it that we are seeing the same thing from the second call to print_al 1 _n e x t ( )? How 
did the current pointer get back to the beginning to start all over again the second time? The answer 
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lies in the fact that PHP function calls are call-by-value, meaning that they copy their arguments 
rather than operating directly on them. Both of the function calls, then, are getting a fresh copy of 
their array argument, which has never itself been disturbed by a call to n ext ( ) . 

p j j £j £j rV For more on under what circumstances functions copy their arguments rather than oper- 
^ ' ating on them directly, see Chapter 5. 

We can test this explanation by passing the arrays by reference rather than by value. If we define the 
same function but call it with ampersands (&) like this: 

pri nt_al l_next ( &$ma j or_ci ty_i nf o ) ; 

pri nt_al l_next ( &$ma j or_ci ty_i nf o ) ; / / again 

We get the following printing behavior: 

Chi cago 
United States 
Stockhol m 
Sweden 
Montreal 
Canada 

There's nothing to print 

i TD'T"^^ [ ^ B * r ' C ' < WB US8t ' *° * BS ' arra y behavior (passing a variable reference to a function) 
~" ' - " -» - ; has been deprecated, so you may get a warning when running this code, in addition to 
seeing the results printed above. 

The reason is that this time the current pointer of the global version of the array was moved by the 
first function call. 



Most of the iteration functions have both a returned value and a side effect. In the case 
of the functions next ( ), prev( ), reset ( ), and end( ), the side effect is to change the 
position of the internal pointer, and what is returned is the value from the key/value pair pointed to 
after the pointer's position is changed. 



Starting over with reset() 

In the preceding section, we wrote a function intended to print out all the values in an array, and we 
saw how it could fail if the array's internal pointer did not start off at the beginning of the list of key/ 
value pairs. The reset ( ) function gives us a way to "rewind" that pointer to the beginning — it sets 
the pointer to the first key/value pair and then returns the stored value. We can use it to make our 
printing function more robust by replacing the call to current( ) with a call to r e s e t ( ) . 

function pri nt_al l_a rray_reset ( $ci ty_a rr ay ) 

( // wa rni ng- - sti 1 1 not reliable. See the function each() 

$current_i tem = reset ( $ci ty_a rray ) ; //rewind, return value 

if ( $current_i tem) 

pri nt ( " $cur rent_i tem<BR> " ) ; 



145 



Part I 



Introducing PHP 



else 

pri nt( "There ' s nothing to print"); 
whi 1 e( $current_i tern = next($city_array) ) 
pr i nt ( " $current_i tem<BR> " ) ; 

} 

This function is somewhat more predictable in that it will always start with the first element, 
regardless of the pointer's location in the array it is handed. (Whether this is a good idea depends, 
of course, on what the function is used for and whether its arguments are passed by value or by 
reference.) 

Perhaps confusingly, we use our call to reset ( ) in the preceding example both for its side effect 
(rewinding the pointer) and for its return value (the first value stored). Alternatively, we could 
replace the first real line of the function body with these two lines: 

reset ( $ci ty_a r ray ) ; // rewind to the first element 
$current_i tem = current ( $ci ty_a may ) ; // the first value 

Reverse order with end() and prev() 

We have seen the functions next ( ) , which moves the current pointer ahead by one, and reset ( ) , 
which rewinds the pointer to the beginning. Analogously, there are also the functions prev ( ) , 
which moves the pointer back by one, and end ( ) , which jumps the pointer to the last entry in the 
list. We can use these, for example, to print our array entries in reverse order. 

function pri nt_al 1 _a r ray„backwa rds ( $ci ty_a rray ) 

( // wa rni ng- -s ti 1 1 not reliable. See the function each() 

$current_i tem = end ( $ci ty_a rray ) ; //fast-forward to last 

if ( $current_i tem) 

pri nt( "$current_i tem<BR>" ) ; 

else 

pri nt( "There ' s nothing to print"); 
whi 1 e( $current_i tem = prev ( $ci ty_a rray ) ) 
pr i nt ( " $current_i tem<BR> " ) ; 

} 

pri nt__al 1 _a r ray_backwa rds ( $ma j or_ci ty_i nf o ) ; 

If we call this on the same $ma j o r_c i ty_i n f o data as in previous examples, we get the same print- 
out in reverse order: 

Canada 
Montreal 
Sweden 
Stockhol m 
United States 
Chicago 
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Extracting keys with key() 

So far, we have printed only the values stored in arrays, even though we are storing keys as well. The 
keys are also retrievable from the internal linked list of an array by using the key ( ) function — this 
acts just like c u r r e n t ( ) except that it returns the key of a key/value pair, rather than the value. (Refer 
to Figure 8-1.) Using the key ( ) function, we can modify one of our earlier printing functions to print 
keys as well as values. 

function pri nt_keys_and_va 1 ues ( $ci ty_a r ray ) 
{ // warning--See the discussion of eachO below 
reset ( $ci ty_a r ray ) ; 

$current_val ue = cur rent ( $ci ty_a r ray ) ; 
$current_key = key ( $ci ty_a rray ) ; 
if ( $current_val ue ) 

print("key: $current_key ; Value: $current_val ue<BR>" ) ; 
else 

pri nt ( "There ' s nothing to print"); 
whi 1 e( $current_val ue = next ( $ci ty_a rray ) ) 
{ 

$current_key = key ( $ci ty_a rray ) ; 

print("Key: $current_key ; Value: $current_val ue<BR>" ) ; 

} 

} 

pri nt_keys_and_val ues ( $ma j or_ci ty_i nf o ) ; 
With the same data as before, this gives us the browser output: 

Key: 0; Value: Chicago 

Key: Chicago; Value: United States 

Key: 1; Value: Stockholm 

Key: Stockholm; Value: Sweden 

Key: 2; Value: Montreal 

Key: Montreal; Value: Canada 

Empty values and the each() function 

We have written several functions that print the contents of arrays by iterating through them and, 
as we have pointed out, all but the f oreach version have the same weakness. Each one of them 
tests for completion by seeing whether next ( ) returns a false value. This will reliably happen 
when the array runs out of values, but it will also happen if and when we encounter a false value 
that we have actually stored. False values include the empty string (" "), the number 0, and the 
Boolean value FALSE, any or all of which we might reasonably store as a data value for some task 
or other. 

To the rescue comes each( ), which is somewhat similar to next( ) but has the virtue of return- 
ing false only after it has run out of array to traverse. Oddly enough, if it has not run out, each ( ) 
returns an array itself, which holds both keys and values for the key/value pair it is pointing at. This 
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characteristic makes each ( ) confusing to talk about because you need to keep two arrays straight: 
the array that you are traversing and the array that each ( ) returns every time that it is called. The 
array that ea ch ( ) returns has the following four key/value pairs: 

■ Key: 0; Value: current-key 

■ Key: 1; Value: current-value 

■ Key: ' key ' ; Value: current-key 

■ Key: ' val ue '; Value: current-value 

The current-key and current-value are the key and value from the array being traversed. In other 
words, the returned array packages up the current key/value pair from the traversed array and offers 
both numerical and string indices to specify whether you are interested in the key or the value. 

p'C- r r-\ ' f In addition to having a different type of return value, each( ) differs from next( ) in 
that e a c h ( ) returns the value that was pointed to before moving the current pointer 
ahead, whereas next( ) returns the value after the pointer is moved. This means that if you start with 
a current pointer pointing to the first element of an array, successive calls to each ( ) will cover each 
array cell, whereas successive calls to next ( ) will skip the first value. 

We can use each ( ) to write a more robust version of a function to print all keys and values in 
an array: 

function pri nt_key s_and_val ues_each ( $ci ty_a r ray ) 
{ // reliably prints everything in array 
reset ( $ci ty_a may ) ; 

while ($array_cell = each ( $ci ty_a may ) ) 
{ 

$cument_val ue = $amay_cel 1 [ ' val ue ' ] ; 
$cument_key = $array_cel 1 [ ' key ' ] ; 

print("Key: $cument_key ; Value: $cument_val ue<BR>" ) ; 

} 

} 

pri nt_key s_and_val ues_each ( $ma j or_ci ty_i nf o ) ; 
Applying this function to our standard sample array gives the following browser output: 

Key: 0; Value: Chicago 

Key: Chicago; Value: United States 

Key: 1; Value: Stockholm 

Key: Stockholm; Value: Sweden 

Key: 2; Value: Montreal 

Key: Montreal; Value: Canada 
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This is exactly the same as was produced by our earlier function pri nt__keys_and_val ues ( ) . The 
difference is that our new function will not stop prematurely if one of the values is false or empty. 



Our last iteration function lets you pass an arbitrary function of your own design over an array, 
doing whatever your function pleases with each key/value pair. The a r r a y_w a 1 k ( ) function takes 
two arguments: an array to be traversed and the name of a function to apply to each key/value pair. 
(It also takes an optional third argument, discussed later in this section.) 

The function that is passed in to a r ray„wa 1 k ( ) should take two (or three) arguments. The first 
argument will be the value of the array cell that is visited, and the second argument will be the 
key of that cell. For example, here is a function that prints a descriptive statement about the string 
length of an array value: 

function pri nt_val ue_l ength( $array_val ue , $array_key_i gnored ) 
{ 

$the_length = st rl en ( $a rray_val ue ) ; 

print("The length of $array_value is $the_l ength<BR> " ) ; 

1 

(Notice that this function intentionally does nothing with the second argument.) Now let's pass this 
function over our standard sample array using a r r ay_wa 1 k ( ) : 

a rray_wal k( $ma j or_ci ty_i nf o , 'pri nt_val ue_l ength ' ) ; 
which gives the browser output: 

The length of Chicago is 7 

The length of United States is 13 

The length of Stockholm is 9 

The length of Sweden is 6 

The length of Montreal is 8 

The length of Canada is 6 

The final flexibility that array _w a 1 k ( ) offers is accepting an optional third argument that, if pres- 
ent, will be passed on, in turn, as a third argument to the function that is applied. This argument 
will be the same throughout the array's traversal, but it offers an extra source of runtime control for 
the passed function's behavior. 



Table 8-2 shows a summary of the behavior of the array iteration functions that we covered in this 
section. Notice that f oreach and list are not included; they are not functions. 



Walking with array_walk() 




You should not alter an array while you are iterating through the array using array 
wal k( ). There is no guarantee how array wal k( ) will behave if you do this. 
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TABLE 8-2 



Functions for Iterating over arrays 


Function 


Arguments 


Side Effect 


Return Value 


c u r r en t ( ) 


One array argument 


None. 


The value from the key/value 
pair currently pointed to by the 
internal "current" pointer (or 
false if no such value). 


next ( ) 


One array argument 


Advances the pointer by 
one. If already at the last 
element, it will move the 
pointer "past the end," 
and subsequent calls to 
current( ) will return 
false. 


The value pointed to after the 
pointer has been advanced (or 
false if no such value). 


prev ( ) 


One array argument 


Moves the pointer back 
by one. If already at the 
first element, will move 
the pointer "before the 
beginning." 


The value pointed to after the 
pointer has been moved back 
(or false if no such value). 


reset ( ) 


One array argument 


Moves the pointer back 
to point to the first key/ 
value pair, or "before the 
beginning" if the array is 
empty. 


The first value stored in the 
array, or false for an empty 
array. 


end ( ) 


One array argument 


Moves the pointer ahead 
to the last key/value pair. 


The last value that is currently 
in the list of key/value pairs. 


pos ( ) 


One array argument 


None. (This function is an 
anas tor cur r enii j .) 


The value of the key/value pair 
that is currently pointed to. 


each ( ) 


One array argument 


Moves the pointer ahead 
to the next key/value pair. 


An array that packages the 
keys and values of the key/ 
value pair that was current 
before the pointer was moved 
(or false if no such pair). The 
returned array stores the key 
and value under its own keys 
0 and 1, respectively, and also 
under its own keys 1 key 1 and 
'value'. 
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Function 



Arguments 



Side Effect 



Return Value 



array_ 
wal k( ) 



1 ) An array 
argument, 2) the 
name of a two- (or 
three-) argument 
function to call on 
each key/value, and 
3) an optional third 
argument. 



This function invokes 
the function named by 
its second argument on 
each key/value pair. Side 
effects depend on the 
side effects of the passed 
function. 



(Returns 1.) 



Summary 



The array is a basic PHP data type and plays the role of both record types and vector array types in 
other languages. PHP arrays are associative, meaning that they store their values in association with 
unique keys or indices. Indices can be either strings or numbers, and are denoted as indices by square 
brackets. (The expression $my_a rray [4] refers to the value stored in $my_array in association 
with the integer index 4, and not necessarily to the 4th element of $my_array.) 

The loose typing of PHP means that any PHP value can be stored as an array. In turn, this means 
that arrays can be stored as array elements. Multidimensional arrays are simply arrays that contain 
other arrays as elements, with a reference syntax of successive brackets. (The expression $my_ 
array[3][4] refers to the element (indexed by 4) of an array that is an element [indexed by 3] of 
$my_array.) 

The array is the standard vehicle for PHP functions that return structured data, so PHP program- 
mers should learn to unpack arrays, even if they are not interested in constructing them. PHP also 
offers a huge variety of functions for manipulating data after you have it stored in an array, including 
functions for counting, summarizing, and sorting. 
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If you need to do serious numerical, scientific, or statistical computa- 
tion, a web-scripting language is probably not where you want to be 
doing it. With that said, however, PHP does offer a generous array of 
functions that nicely cover most of the mathematical tasks that arise in web 
scripting. It also offers some more advanced capabilities such as arbitrary- 
precision arithmetic and access to hashing and cryptographic libraries. 

The PHP designers have, quite sensibly, not tried to reinvent any wheels 
in this department. Instead, they found about 18 perfectly good wheels by 
the side of the road and built a lightweight fiberglass chassis to connect 
them all together. Many of the more basic math functions in PHP are simple 
wrappers around their C counterparts (for more on this, see the sidebar "A 
Glimpse behind the Curtain" in Chapter 27, which will cover PHP's math- 
ematics capabilities in greater detail). 



IN THIS CHAPTER 



Numerical types 
Mathematical operators 
Simple math functions 



Random numbers 



Numerical Types 



PHP has only two numerical types: integer (also known as long), and double 
(aka float), which correspond to the largest numerical types in the C lan- 
guage. PHP does automatic conversion of numerical types, so they can be 
freely intermixed in numerical expressions, and the "right thing" will typi- 
cally happen. PHP also converts strings to numbers where necessary. 
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In situations where you want a value to be interpreted as a particular numerical type, you can force a 
typecast by prepending the type in parentheses, such as: 

(double) $my_var 
(integer) $my_var 

Or you can use the functions i n t v a 1 ( ) and doublevaK), which convert their arguments to inte- 
gers and doubles, respectively. 

f tj r jv-'W" "rj-'r-V For more details on the integer and double types, see Chapter 4. 

Mathematical Operators 

Most of the mathematical action in PHP is in the form of built-in functions rather than in the form 
of operators. In addition to the comparison operators covered in Chapter 5, PHP offers five opera- 
tors for simple arithmetic, as well as some shorthand operators that make incrementing and assigning 
statements more concise. 

Arithmetic operators 

The five basic arithmetic operators are those you would find on a four-function calculator, plus the 
modulus operator (%). (If you are unfamiliar with modulus, see the discussion following Table 9-1.) 
The operators are summarized in Table 9-1. 



TABLE 9-1 



Arithmetic Operators 


Operator 


Behavior 


Examples 


+ 


Sum of its two arguments. 


4 + 9.5 evaluates to 13 . 5 




If there are two arguments, the right- 
hand argument is subtracted from the 
left-hand argument. If there is just a 
right-hand argument, then the negative 
of that argument is returned. 


50 - 75 evaluates to -25 
-3.9 evaluates to - 3.9 


* 


Product of its two arguments. 


3.14 * 2 evaluates to 6.28 


/ 


Floating-point division of the left-hand 
argument by the right-hand argument. 


5/2 evaluates to 2 . 5 


% 


Integer remainder from division of left- 
hand argument by the absolute value of 
the right-hand argument. (See discussion 
in the following section.) 


101 % 50 evaluates to 1 
999 % 3 evaluates to 0 
43 % 94 evaluates to 43 
-12 % 10 evaluates to -2 
-12 % -10 evaluates to -2 
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Arithmetic operators and types 

With the first three arithmetic operators (+, -, *), you should expect type contagion from doubles to 
integers; that is, if both arguments are integers, the result will be an integer, but if either argument is 
a double, then the result will be a double. With the division operator, there is the same sort of conta- 
gion, and in addition the result will be a double if the division is not even. 

FTp™^ \ ^ y° u war, t integer division rather than floating-point division, simply coerce or convert 
the division result to an integer. For example, i ntva 1 (5 / 2 ) evaluates to the integer 2. 

Modular arithmetic is sometimes taught in school as clock arithmetic. The process of taking one num- 
ber modulo to another amounts to "wrapping" the first number around the second, or (equivalently) 
taking the remainder of the first number after dividing by the second. The result of such an opera- 
tion is always less than the second number. 

Roughly speaking, a conventional civilian analog clock displays hours elapsed modulo 12, while 
military time is modulo 24. (The roughly in the previous sentence is because the real modulus 
function converts numbers to the range 0 to n-1, rather than the range 1 to n. If bell-tower clocks 
respected this, noontime would be marked by silence, rather than by 12 chimes.) 

The modulus operator in PHP (%) expects integer arguments — if it is given doubles, they will sim- 
ply be converted to integers (by truncation) first. The result is always an integer. 

Most programming languages have some form of the modulus operator, but they differ in how they 
handle negative arguments. In some languages, the result of the operator is always positive, and -2 
% 26 equals 24. In PHP, though, -2 % 26 is -2, and, in general, the statement $mod = $f i rst_num % 
$second_num is exactly equivalent to the expression: 

i f ( $f i rst_num >= 0 ) 

$mod = $first_num % abs ( $second_num ) ; 
else 

$mod = - ( abs ( $f i rst_num) % abs ( $second_num ) ) ; 
where a bs ( ) is the absolute value function. 

Incrementing operators 

PHP inherits a lot of its syntax from C, and C programmers are famously proud of their own con- 
ciseness. The incrementing/decrementing operators taken from C make it possible to more concisely 
represent statements like $count = $ c o u n t + 1, which tend to be typed frequently. 

The increment operator (++) adds one to the variable it is attached to, and the decrement operator 
(- -) subtracts one from the variable. Each one comes in two flavors, postincrement (which is placed 
immediately after the affected variable), and preincrement (which comes immediately before). Both 
flavors have the same side effect of changing the variable's value, but they have different values as 
expressions. The postincrement operator acts as if it changes the variable's value after the expres- 
sion's value is returned, whereas the preincrement operator acts as though it makes the change 
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first and then returns the variable's new value. You can see the difference by using the operators in 
assignment statements, like this: 

Icount = 0; 
$result = $count++; 

print("Post ++: count is $count, result is I res ul t<BR> " ) ; 

$count = 0; 

$resul t = ++$count ; 

print("Pre ++: count is $count, result is $result<BR>"); 

$count = 0; 

$resul t = $count-- ; 

print("Post --: count is $count, result is $resul t<BR>" ) ; 
$count = 0; 
$result = --$count; 

print("Pre --: count is $count, result is $result<BR>"); 
which gives the browser output: 

Post ++: count is 1, result is 0 
Pre ++: count is 1, result is 1 
Post --: count is -1, result is 0 
Pre --; count is -1, result is -1 

In this example, the statement Sresult = $count++; is exactly equivalent to: 

$result = $count; 
$count = Icount + 1 ; 

while Sresult = ++$count; is equivalent to: 

$count = $count + 1 ; 
Sresult = $count; 

Assignment operators 

Incrementing operators like ++ save keystrokes when adding one to a variable, but they don't help 
when adding another number or performing another kind of arithmetic. Luckily, all five arithmetic 
operators have corresponding assignment operators (+=, -=, *=, /=, and %=) that assign to a variable 
the result of an arithmetic operation on that variable in one fell swoop. The statement: 

$count = Icount * 3; 

can be shortened to: 

Icount *= 3; 
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and the statement: 

$count = $count + 17; 
becomes: 

$count += 17; 

Comparison operators 

PHP includes the standard arithmetic comparison operators, which take simple values (numbers or 
strings) as arguments and evaluate to either TRUE or FALSE: 

p pi £j ^cj"-. Pp ^ or exam P' es °f usm g the comparison operators and also some gotcha issues with com- 
' ' paring doubles and strings, see Chapter 5. 

■ The < (less than) operator is true if its left-hand argument is strictly less than its right-hand 
argument but false otherwise. 

■ The > (greater than) operator is true if its left-hand argument is strictly greater than its 
right-hand argument but false otherwise. 

■ The <= (less than or equal) operator is true if its left-hand argument is less than or equal to 
its right-hand argument but false otherwise. 

■ The >= (greater than or equal) operator is true if its left-hand argument is greater than or 
equal to its right-hand argument but false otherwise. 

■ The == (equal to) operator is true if its arguments are exactly equal but false otherwise. 

■ The ! = (not equal) operator is false if its arguments are exactly equal and true otherwise. 
This operator is the same as <>. 

■ The === operator (identical to) is true if its two arguments are exactly equal and of the 
same type. 

■ The !== operator (not identical to) is true if the two arguments are not equal or not of the 
same type. 




The i denti cal to operator (===)can, at times, be a necessary antidote to PHP's auto- 
matic type conversions. None of the following expressions will have a t r u e value: 



2 === 2.0 
2 === "2" 
"2.0" === 2.0 

0 === FALSE 

This behavior can be invaluable, for example, if you have a function that returns a string when it suc- 
ceeds (which might be the empty string) and a FALSE value when it fails. Testing the truth of the return 
value would confuse FALSE with the empty string, whereas the identical operator can distinguish them. 
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Precedence and parentheses 

Operator precedence rules govern the relative stickiness of operators, deciding which operators in 
an expression get first claim on the arguments that surround them. You can find a complete table 
of all operator precedences in the manual at www .php.net, but the important precedence rules for 
arithmetic are: 

■ Arithmetic operators have higher precedence (that is, bind more tightly) than comparison 
operators. 

■ Comparison operators have higher precedence than assignment operators. 

■ The *, /, and % arithmetic operators have the same precedence. 

■ The + and - arithmetic operators have the same precedence. 

■ The *, /, and % operators have higher precedence than + and -. 

■ When arithmetic operators are of the same precedence, associativity is from left to right 
(that is, a number will associate with an operator to its left in preference to the operator on 
its right). 

If you find the precedence rules difficult to remember, the next person who reads your code may 
have the same problem, so feel free to parenthesize when in doubt. For example, can you easily fig- 
ure out the value of this expression? 

l + 2*3-4-5/4%3 

As it turns out, the value is 2, as you can see more easily when we add parentheses that are not, 
strictly speaking, necessary: 

((l+(2*3))-4)-((5/4)%3) 



Simple Mathematical Functions 

The next step up in sophistication from the arithmetic operators consists of miscellaneous functions 
that perform tasks like converting between the two numerical types (which we discussed in Chapter 4) 
and finding the minimum and maximum of a set of numbers (see Table 9-2). 

For example, the result of the following expression: 

min(3, abs(-3), max ( round ( 2 . 7 ) , ceil (2.3) , floor(3.9))) 

is 3, because the value of every function call is also 3. 
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TABLE 9-2 



Simple Math Functions 


Function 


Behavior 


f 1 oor ( ) 


Takes a single argument (typically a double) and returns the largest integer that is less 
than or equal to that argument. 


ceil () 


Short for ceiling — takes a single argument (typically a double) and returns the smallest 
integer that is greater than or equal to that argument. 


round ( ) 


Takes a single argument (typically a double) and returns the nearest integer. If the 
fractional part is exactly 0.5, it returns the nearest even number. 


abs() 


Short for absolute value — if the single numerical argument is negative, the 
corresponding positive number is returned; if the argument is positive, the argument 
itself is returned. 


m i n ( ) 


Takes any number of numerical arguments (but at least one) and returns the smallest of 
the arguments. 


max( ) 


Takes any number of numerical arguments (but at least one) and returns the largest of 
the arguments. 



Randomness 

PHP's functions for generating pseudo-random numbers are summarized in Table 9-3. (If you are 
new to random number generation and are wondering what the pseudo is all about, please see the 
accompanying sidebar.) 

There are two random number generators (invoked with rand ( ) and mt_rand ( ) , respectively), 
each with the same three associated functions: a seeding function, the random number function 
itself, and a function that retrieves the largest integer that might be returned by the generator. 

The particular pseudo-random function that is used by rand ( ) may depend on the particular 
libraries that PHP was compiled with. By contrast, the mt_rand ( ) generator always uses the same 
random function (the Mersenne Twister), and the author of mt„rand ( )'s online documentation 
argues that it is also faster and "more random" (in a cryptographic sense) than r a n d ( ) . We have no 
reason to believe that this is not correct, so we prefer mt_rand ( ) to rand ( ) . 
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TABLE 9-3 



Random Number Functions 


Function 


Behavior 


s r 3 n d ( ) 


Takes a single positive integer argument and seeds the random number generator with it. 


rand( ) 


If called with no arguments, returns a "random" number between 0 and RAND_MAX 
(which can be retrieved with the function getrandmaxC )). The function can also be 
called with two integer arguments to restrict the range of the number returned — the 
first argument is the minimum and the second is the maximum (inclusive). 


getrandmax( ) 


Returns the largest number that may be returned by rand ( ) . This number is limited to 
32768 on Windows platforms. 


mt_s rand ( ) 


Like s rand ( ), except that it seeds the "better" random number generator. 


mt_rand ( ) 


Like rand ( ), except that it uses the "better" random number generator. 


mt_ 

getrandmax( ) 


Returns the largest number that may be returned by mt_rand ( ) . 



.J fjj"*"™ [ ^ n some wsions and some platforms, you can apparently get seemingly random 

numbers from ra nd () and mt_r a nd () without seeding first — this should not be relied 
upon, however, both for reasons of portability and because the unseeded behavior is not guaranteed. 



Seeding the generator 

The typical way to seed either of the PHP random number generators (using mt_s r a n d ( ) or 
s r a n d ( ) ) looks like this: 

mt_srand( (double ) microti me ( )*1 000000) ; 

This sets the seed of the generator to be the number of microseconds that have elapsed since the 
last whole second. (Yes, the typecast to doubl e is necessary here, because mi croti me ( ) returns a 
string, which would treated as an integer in the multiplication but for the cast.) Please use this seed- 
ing statement even if you don't understand it — just place it in any PHP page, once only, before you 
use the corresponding mt„r a n d ( ) or rand( ) functions, and it will ensure that you have a varying 
starting point and therefore random sequences that are different every time. This particular seeding 
technique has been thought through by people who understand the ins and outs of pseudo-random 
number generation and is probably better than any attempt an individual programmer might make 
to try something trickier. 

pTn" 7 " I Although the random number functions only return integers, it is easy to convert a ran- 
■d"^^^^™ 1 dom integer in a given range to a corresponding floating-point number (say, one between 
0.0 and 1.0 inclusive) with an expression like rand( ) / getrandmax( ). You can then scale and shift 
the range as desired (to, say, a number between 100.0 and 120.0) with an expression like 100.0 + 

20.0 * (rand( ) / getrandmax( )). 
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Pseudo-Random Number Generators 



As with all programming languages, the "random" number functions offered by PHP are really implemented 
by pseudo-random number generators. This is because conventional computer architectures are deter- 
ministic machines that will always produce the same results given the same starting conditions and inputs and 
have no good source of randomness. (Here we're talking about the ideal computer as it is supposed to work, 
not the actual physically embodied, power-interruptible, cosmic-ray flippable, seemingly very random machines 
we all struggle with daily!) You could imagine connecting a conventional computer to a source of random bits 
such as a mechanical coin-flip reader, or a device that observed quantum-level events, but such peripherals 
don't seem to be widely available at this time. 

So we must make do with pseudo-random generators, which produce a deterministic sequence of numbers 
that looks random enough for most purposes. They typically work by running their initial input number (the 
seed) through a particular mathematical function to produce the first number in the sequence; each subsequent 
number in the sequence is the result of applying that same function to the previous number in the sequence. 
The sequence will repeat at some point (once it generates a particular number for the second time, it is doomed 
to follow the same sequence as it did the first time around), but a good iteration function will generate a very 
long sequence of numbers that have little apparent pattern before the loop occurs. 

How do you choose a seed to start off with? Because of the generator's determinism, if you hardcode a PHP 
page to have a particular seed, that page will always see the same sequence from the generator. (Although this 
is not usually what you want, it can be an invaluable trick when you are trying to debug behavior that depends 
on the particular numbers that are generated.) The typical seeding technique is to use a fast-changing digit from 
the system clock as the initial seed — although those numbers are not exactly random, they are likely to vary 
quickly enough that subsequent page executions will start with a different seed every time. 

Here's some representative code that uses the pseudo-random functions: 

pri nt( "Seedi ng the generator<BR>" ) ; 
mt_srand((double)microtime() * 1000000); 
print("With no arguments: " . mt_rand() . "<BR>"); 
print("With no arguments: " . mt_rand() . "<BR>"); 
print("With no arguments: " . mt„rand() . "<BR>"); 
print("With two arguments: " . 

mt_rand(27, 31) . "<BR>"); 
print("With two arguments: " . 

mt_rand(27, 31) . "<BR>"); 
print("With two arguments: " . 

mt_rand(27, 31) . "<BR>"); 

with the browser output: 



Seeding the generator 

With no arguments: 1962311688 

With no arguments: 1494083765 

With no arguments: 1224081997 

With two arguments: 31 

With two arguments: 27 

With two arguments: 30 
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Obviously, if you run exactly this code, you will get numbers that differ from those in the output 
shown here, because the point of seeding the generator this way is to ensure that different execu- 
tions produce different sequences of numbers. 

r- 1 -'j O" j^j'- " ' n some °' c ' versions of PHP3, the rand( ) function buggily ignored its arguments, 
SBmmUmmm^K: returning numbers between 0 and getrandmax( ) regardless of restrictions. We have 
also heard some reports of that behavior under more recent Windows implementations. If you suspect 
that you are suffering from such a bug, you can define your own restricted version of rand ( ) like this: 

function my_rand ($min, $max) 
{ 

return(rand( ) % (($max - $min) + 1) 
+ $ m i n ) ; 

} 

Unlike rand ( ), this version requires the mi n and max arguments. 

Example: Making a random selection 

Now let's use the random functions for something useful (or, at least, something that could be used 
for something useful). The following two functions let you construct a random string of letters, 
which could, in turn, be used as a random login or password string: 

function random_cha r ( $stri ng ) 
{ 

Slength = strl en ( $stri ng ) ; 
$position = mt_rand(0, $length - 1); 
return($string[$position]); 

} 

function random_stri ng ( $charset_stri ng , $length) 
{ 

$return_stri ng = ""; // the empty string 
for ($x = 0; $x < $length; $x++) 

$return_stri ng .= random_cha r ( $cha rset_st ri ng ) ; 
return ( $ return_st ri ng ) ; 

} 

The random_cha r ( ) function chooses a character (or, actually, a substring of length 1) from its input 
string. It does this by restricting the mt_rand ( ) function to positions within the length of the string 
(with chars numbered starting at zero), and then returning the character that is at that random posi- 
tion. The ran d om_s t r i n g ( ) function calls ran d om_c h a r ( ) a number of times on a string repre- 
senting the universe of characters to be chosen from and concatenates a string of the desired length. 

Now, to demonstrate this code, we first seed the generator, define our universe of allowable charac- 
ters, and then call random_st r i ng ( ) a few times in a row: 

mt_srand( ( doubl e )mi croti me ( ) * 1000000); 
$charset = " abcdef ghi j kl mnopqrstuvwxyz " ; 
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$random_stri ng = random_stri ng( $charset , 8); 
pri nt ( " random_st ri ng : $ random_st ri ng<BR> " ) ; 
$random_stri ng = random_stri ng( $charset , 8); 
pri nt( " random_stri ng : $random_stri ng<BR>" ) ; 
$ random_stri ng = random_stri ng( $charset , 8); 
pri nt( " random_stri ng : $random_stri ng<BR>" ) ; 

with the result: 

random_stri ng : eisexkio 
random_stri ng : mkvflwfy 
random_stri ng : gpulbwth 

In this example, we seed the generator only once, and we draw that seed value from the system 
clock. Notice what happens if we make the mistake of repeatedly seeding the generator with the 
same value: 

mt_srand(43) ; 

$ random_stri ng = random_stri ng( $charset , 8); 
pri nt( " random_stri ng : $random_stri ng<BR>" ) ; 

mt__srand(43) ; 

$random_stri ng = random_stri ng( $charset , 8); 
pri nt ( " random_st ri ng : $ random_st ri ng<BR> " ) ; 

mt_srand(43) ; 

$ random„stri ng = random„stri ng( $charset , 8); 
pri nt( " random_stri ng : $random_stri ng<BR>" ) ; 

Because the sequence that is generated depends deterministically on the seed, we get the same 
behavior each time: 

random_stri ng : qgkxvurw 
random_stri ng : qgkxvurw 
random_stri ng : qgkxvurw 

In these examples, we chose to draw random characters from strings, but this kind of selection pro- 
cess is generalizable to draw items from arrays or to be used in any situation that requires choosing 
random members from a set. All you need is the universe of items, a way to put them in numerical 
order, and a way to retrieve them by order number, and you can then use the rand ( ) or mt_rand ( ) 
function to choose a random order number for the retrieval. 



Summary 

The highlights of PHP math are summarized in Table 9-4. Refer to Chapter 27 for more advanced 
mathematical concepts as they are handled by PHP. 
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TABLE 9-4 



Summary of PHP Math Operators and Functions 


Category 


Description 


Arithmetic 
operators 


Operators +, -, *, /, % perform basic arithmetic on integers and doubles. 


Incrementing 
operators 


The ++ and - - operators change the values of numerical variables, increasing them 
by one or decreasing them by one (respectively). The value of the postincrement form 
( $ va r++) is the same as the variable's value before the change; the value of the 
preincrement form (++$var) is the variable's value after the change. 


Assignment 
operators 


Each arithmetic operator (like +) has a corresponding assignment operator (+=). The 
expression $ count += 5 is equivalent to $ count = $count + 5. 


Comparison 
operators 


These operators (<,<=,>,>=,==,!=) compare two numbers and 
return either true or fal se. The === operator is true if and only if its arguments 
are equal and of the same type while the !== is true if the arguments are not equal or 
aren't of the same type. 


Basic math 
functions 


f 1 oor ( ), ceil ( ), and round ( ) convert doubles to integers, mi n ( ) and max ( ) 
take the minimum and maximum of their numerical arguments, and abs ( ) is the 
absolute value function. 
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Even though we've tried to give clear instructions, and you've no 
doubt followed them to the letter, problems can still arise. This 
chapter lays out some of the most common problems by symptom 
and suggest some frequent causes. 



CROSS-REF 



There is a whole other universe of gotchas involving database 
connectivity. This chapter deals with PHP-only problems. You 
may want to skip ahead to Chapter 19 if you're having problems with PHP 
and a database. Also, problems specific to certain more advanced features 
(including sessions, cookies, building graphics, e-mail, and XML) are dealt 
with in their individual chapters in Parts III and IV. 



Installation-Related Problems 

Instead of getting moralistic about people who rush through their installs 
without understanding the documentation, we'll point out a few common 
symptoms that characteristically appear when you've just installed PHP for 
the first time. 



I If you are seeing similar errors but are confident that your 
sasia installation is stable, follow the cross-references to later parts of 
this chapter. 



IN THIS CHAPTER 



Installation-related problems 
Rendering problems 
Failures to load page 



Parse errors 



File permissions 
Missing includes 



Unbound variables 



Function problems 
Math problems 



Timeouts 
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Symptom: Text of file displayed in browser window 

If you are seeing the text of your PHP script instead of the resulting HTML, the PHP engine is clearly 
not being invoked. Check that you are accessing the site through the web server and not via the file- 
system. Use this: 

http://localhost/mysite/mypage.php 

rather than this: 

file://home/httpd/httnl/mysite/mypage.php 

Symptom: PHP blocks showing up as text under 
HTTP or browser prompts you to save file 

The PHP engine is not being invoked properly. If you're properly requesting the file via HTTP as 
explained previously, the most common reason for this error is that you haven't specified all the file 
extensions you want to be served by the web server and parsed with the PHP interpreter. Go back 
to Chapter 2, and review how to configure your Web server to recognize PHP file extensions. The 
second most common reason is that your php . i ni file is in the wrong place or has a bad configu- 
ration directive. 

f tj q"^< J- J rj. >V" If you see PHP code in your Web browser and you have a stable installation, your prob- 
~"' J ~ ~^~* > J lem is probably due to missing PHP tags. See the "Rendering Problems" section later in 

this chapter. 

Symptom: Server or host not found/Page cannot 
be displayed 

If your browser can't find your server, you may have a DNS (Domain Name Service) or Web-server 
configuration issue. 

If you can get to the site via IP address rather than domain name, your problem is probably DNS-related. 

If you cannot get to the site via IP address for a new installation, it's likely you haven't successfully 
bound the IP address to your network interface or configured the web server to handle requests for 
a particular domain (see Chapter 2). If you can't get to the site via IP address for a previously work- 
ing installation, most likely your Web server is down or unreachable for a reason not related to PHP. 

Rendering Problems 

This section covers problems where PHP does not report an error per se, but what you see is not 
what you thought you would get. 
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Symptom: Totally blank page 

A blank page could be caused by any number of issues. Usually, it's caused by a fatal error in the 
PHP code from which the PHP interpreter cannot recover. Begin by debugging at the top of the PHP 
file that you're trying to visit by placing a di e ( ) after the opening <?php tag: 

<?php 

d i e ( p r i n t "hello"); 

If you refresh the page, and see the word hello in the browser, then you've ruled out problems with 
the web server and the PHP module itself. Continue to move the d i e ( ) statement further down into 
the PHP code until you reproduce the blank page error. Don't forget that any files included through 
a "requi re," "requi re_once," "i ncl ude," or the like could also be causing the script to fail. If 
you place the d i e ( ) statement just before an included file and it works and then move the d i e ( ) 
just after the included file and the script fails, then you've determined that the problem (or at least a 
problem) lies in the included file. 

Of course, another possible answer in this case is that the PHP module is not working at all. Test 
by browsing a different page in the same directory that you've previously verified is being correctly 
handled by PHP. 

Also see the "Timeouts" section near the end of this chapter for more information on what happens 
when you write code that runs "forever." 

Finally, you might be seeing a blank screen if your PHP hits a more or less fatal error but you have 
error reporting turned off. Error reporting should probably be turned off for production servers 
for security reasons, but error reporting to the browser is actually a huge help for development 
servers. Check your php . i ni file's di spl ay_errors setting and make sure the settings are what 
you expected. If you really dislike error reporting to the browser, you need to make heavy use of 
the error_l og function in exception handling. See Chapters 30 and 31 for more debugging tips. 

Symptom: PHP code showing up in Web browser 

If you are seeing literal PHP code in your browser, rather than a rendering of the HTML it should 
be producing, you may have omitted a PHP start tag somewhere. (This assumes that you have had 
PHP running successfully and that you are using the correct tags for your installation. If not, see the 
"Installation-Related Problems" section near the beginning of this chapter.) 

It's easy to forget that PHP treats included files as HTML, not as PHP, unless you tell it otherwise 
with a start tag at the beginning of the file. For example, assume that we load the following PHP file: 

<HTMLXHEADX/HEADXBODY> 
<?php include(" secret. php"); 
secret_f uncti on ( ) ; ?> 
</BODYX/HTML> 
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which includes the file secret, php, which in turn looks like this: 

function secret_f uncti on () 
{ 

echo "Open sesame ! " ; 

} 

The result is shown in Figure 10-1. 



FIGURE 10-1 
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This can be fixed by adding PHP tags to the included file like this: 
<?php 

function secret_f uncti on () 
{ 

echo "Open sesame!"; 

} 

?> 



Failures to Load Page 

A couple of different kinds of errors are seen when PHP is unable to find a file that you have asked it 
to load. 

Symptom: Page cannot be found 

If your browser can't find a PHP page you've created, and you have recently installed PHP, please see the 
section "Installation-Related Problems" earlier in this chapter. If you get this message when you have 
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been loading other PHP files without incident, it's quite likely you are just misspelling the filename or 
path. Alternatively, you may be confused about where the web server document root is located. 

Symptom: Failed opening [file] for inclusion 

When including files from PHP files, we sometimes see errors like this (on a Unix platform, the file 
paths would be different): 

Warning Failed opening 'C:\InetPub\wwwroot\asdf.php' for 
inclusion ( i ncl ude_path= ' ' ) in [no active file] on line 0 

It turns out that this is the included-file version of Page cannot be found — that is, PHP hasn't 
even gotten to loading the first line of the active file. There is no active file because no file by that 
name could be found. 

It's also possible that you will see this message as a result of incorrect permissions on the file you are 
trying to load. 



Parse Errors 

The most common category of error arises from mistyped or syntactically incorrect PHP code, which 
confuses the PHP parsing engine. 

Symptom: Parse error message 

Although the causes of parsing problems are many, the symptom is almost always the same: a parse 
error message like that in Figure 10-2. 



FIGURE 10-2 
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The most common causes of parse errors, detailed in the subsections that follow, are all quite minor 
and easy to fix, especially with PHP lighting the way for you. However, every parse error returns 
the identical message (except for filenames and line numbers) regardless of cause. Any HTML that 
may be in the file, even if it appears before the error-causing PHP fragment, will not be displayed or 
appear in the source code. 

The missing semicolon 

If each PHP instruction is not duly finished off with a semicolon, a parse error will result. In this 
sample fragment, the first line lacks a semicolon, and therefore, the variable assignment is never 
completed. 

What we have here is 
<?php 

$ Problem = "a silly misunderstanding" 
echo $Problem; ?>. 



No dollar signs 

Another very common problem is that a dollar sign prepending a variable name is missing. If the 
dollar sign is missing during the initial variable assignment, like this: 

What we have here is 
<?php 

Problem = "a big ball of earwax"; 
echo $Problem; ?>. 

a parse error message will result. However, if instead the dollar sign is missing from a later output of 
the variable, like this: 

What we have here is 
<?php 

$Problem = "a big ball of earwax"; 
pri nt ( " Probl em" ) ; ?> . 

PHP will not indicate a parse error. Instead, you will get the screen shown in Figure 10-3. 

This is an excellent example of why you should not rely on PHP to tell you something is wrong. 
Although PHP's error messages are more informative than most, errors such as this are easily missed 
if your proofreading efforts aren't up to par. 

pTn™ l If you spend any significant portion of your time debugging PHP code, an editor that can 
jump to specific line numbers can be invaluable. Note that the actual mistake that caused 
the error may be on the line that PHP complains about, or before it, but never after it. For example, 
because there's nothing wrong with commands that span several lines, a missed semicolon won't cause 
a parse error until PHP tries to interpret subsequent lines as part of the same statement. Some inte- 
grated development environments (IDEs) will do on-the-fly syntax checking while you write. These can 
be helpful to spot the errors before they get to the server, while you're still coding. 
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FIGURE 10-3 
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Mode issues 

Another family of glitches arises from faulty transitions in and out of PHP mode. 

A parse error will result if you fail to close off a PHP block properly, as in: 

What we have here is 
<?php 

$Problem = "Bad Code!"; 
echo $Problem; . 

This particular mode issue is very common with short PHP blocks. Conversely, if you fail to begin 
the PHP block properly, the rest of the intended block will simply appear as HTML. 

A slightly more tricky issue is engendered by the use of the minimal PHP style, which entails weav- 
ing in and out of HTML mode frequently. (See the discussion of minimal versus maximal style in 
Chapter 33.) For instance, this fragment (which omits the ?> after the first curly brace, when we 
intend to return to HTML mode) will return a parse error: 

<?php if ( ! IsSet(lstage) ) 
{ 

What we have here is 
<?php 

$Problem = "an awful kerfuffle "; 
print("$Problem"); ?>. 
<?php 
) else { 

pri nt( "$Stage" ) ; ( 

?> 



171 



Part I 



Introducing PHP 



Another instance of a very common problem is this one, which combines the short block and 
weaving-in-and-out-of-HTML issues neatly: 

<F0RM> 

<INPUT TYPE="TEXT" SIZE=15 NAME=" Fi rstName" 
VALUE="<?php print("$FirstName"); ?>"> 
<INPUT TYPE="TEXT" SIZE=15 NAME=" LastName" 
VALUE="<?php print("$LastName") ; ?>"> 
<INPUT TYPE="TEXT" SI ZE=10 NAME="PhoneNumber" 
VALUE="<?php print($PhoneNumber") ; ?>" 
<INPUT TYPE="SUBMIT" NAME="Submi t"> 
</F0RM> 

A PHP double-quote and the HTML closing bracket have been forgotten on the PhoneNumber 
input line here. This will both cause a parse error and prevent the Submit button from appearing 
on a client browser. 

The sample code is meant to demonstrate how easy it can be to forget an element on a crowded 
page with lots of small but important symbols. You can reduce this type of error either by using a 
good programmer's text editor or by completing and testing the HTML first and adding the PHP 
later (or both). 

Unescaped quotation marks 

Another type of parse error is characteristic of maximal PHP: the unescaped quotation mark. 
<?php 

print("She said, /"What we have here is "); 
$Problem = "a difference of opinionV"; 
pri nt( "$Probl em" ) ; ?> . 

In this case, the double-quote just before the word What is incorrectly, and therefore ineffectively, 
escaped by a forward slash rather than a backslash. If you simply forgot the backslash, the effect 
would be the same. 

Unterminated strings 

Failing to close off a quoted string can cause parse errors that refer to line numbers far away from 
the source of the problem. For example, a code file like this: 

print("I am a guilty print statement!); // line 5 
// 47 lines of PHP code omitted ... 

print("I am an innocent print statement!"); // line 53 

might well produce a parse error that complains about line 53. This is because PHP is happy to 
include any text you might want in a quoted string, including many lines of your own code. This 
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inclusion finishes happily with the first double-quote in line 53, and then the parser finds the sym- 
bol I , which it can't figure out how to interpret as PHP code. 

If the quotation mark symbol that begins the unterminated string happens to be the last one in the 
file, the line number in the complaint will be the last line in the file — again, probably far away from 
the scene of the crime. 

Other parse error causes 

The problems we have named are not an exhaustive list of the sources of parse errors. Anything 
that makes a PHP statement malformed will confuse the parser, including unclosed parentheses, 
unclosed brackets, operators without arguments, control structure tests without parentheses, and 
so on. Sometimes the parse error will include a statement about what PHP was expecting and didn't 
find, which can be a helpful clue. If the line of the parse error is the very last line of the file, it usu- 
ally means that some kind of enclosure (quotation marks, parentheses, braces) was opened and 
never closed, and PHP kept on hoping until the very end. 



Missing Includes 

In addition to loading top-level source files, PHP needs to be able to load any files you bring in via 
i ncl ude( ) or requi re( ). 

Symptom: Include warning 

This kind of error is shown in Figure 10-4. 



FIGURE 10-4 
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The problem is that you call somewhere in the script for a file to be included, but PHP can't find it. 
Check to see that the path is correct. You might also have a case sensitivity or other typographic 
issue. Note the important difference between i n c 1 u d e ( ) and r e q u i re ( ) . If a file is included 
and PHP can't locate the file, execution of the script will continue with a PHP warning. If a file is 
required and PHP can't locate that file, execution will stop with an error. 



Unbound Variables 

PHP is different from many programming languages in that variables do not have to be declared 
before being assigned, and (under its default settings) PHP will not complain if they are used before 
being assigned (or bound) either. As a result, forgetting to assign a variable will not result in direct 
errors — either you will see puzzling, but error-free output, or you will see a downstream error that 
is a result of variables not having the values you expected. (If you would rather be warned, you can 
set the error-reporting level in p h p . i n i or by evaluating e r r o r„r e p o r t i n g ( E_A L L ) .) Some symp- 
toms of this kind of problem follow. 

Symptom: Variable not showing up in print string 

If you embed a variable in a double-quoted string ("like $ t h i s ") and then print the string using 
print or echo, the variable's value should show up in the string. If it seems to not be there at all in 
the output ("1 i ke "), the variable has probably never been assigned. 

Symptom: Numerical variable unexpectedly zero 

Although it's possible to have a math error or misunderstanding result in this symptom, it's much 
more likely that you believe that the variable has been assigned when it actually hasn't been. 

Causes of unbound variables 

PHP automatically converts the types of variables depending on the context in which they are used, 
and this is also true of unbound variables. In general, unbound variables are interpreted as 0 in a 
numerical context, " " in a string context, FALSE in a Boolean context, and as an empty array in an 
array context. The following code shows the effect of forgetting to bind two variables ($ two_s t r i n g 
and $three); the resulting display appears in Figure 10-5: 

< ? p h p 

$one_stri ng = " one " ; 
$three_stri ng = "three"; 
$one = 1 ; 
$two = 2; 

print("This math is as easy 
$three_string!<BR>") ; 
pri nt( "$one_stri ng is equal 
pri nt ( " $two_st ri ng is equal 



as $one_string, $two_string, 

to $one<BR>" ) ; 
to $two<BR>" ) ; 
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pri nt( "$three_stri ng is equal to $three<BR>" ) ; 
pri nt ( " $one_stri ng divided by $two_string is " . 

($one / $two) . "<BR>"); 
pri nt ( " $one„st ri ng divided by $three_stri ng is " . 

(lone / $three) . "<BR>") ; 

?> 



FIGURE 10-5 
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Case problems 

Variables in PHP are case sensitive, so the same name with different capitalization results in a dif- 
ferent variable . Even after a value is assigned to the variable $ M i s s i s s i p p i , the variable $ m i s - 
si s s i p p i will still be unbound. (Capitalization aside, variables that are this difficult to spell are 
probably to be avoided for the same reason.) 

Scoping problems 

As long as no function definitions are involved, PHP variable scoping is simple: Assign a variable, 
and its value will be there for you from that point on in that script's execution (until the variable is 
reassigned). However, the only variables that are available inside a function body are the function's 
formal parameters and variables that have been declared to be global — if you have a puzzling, 
unbound variable inside a function, this is probably something you've forgotten. In the following 
code, for example, the variable $ s e r i a 1 _n o is neither passed in to the function nor declared to be 
global: 

$name = "Steve Suehring"; 
$rank = "Intarweb Programmer"; 
$ s e r i a 1 _n o = " 4 " ; 

function Answer( $name) 
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global $rank; 

print("Name: $name; Rank: $rank; 

serial no: $seri al_no<BR>" ) ; 

} 

Answer ( $name ) ; 
The resulting browser output looks like: 

Name: Steve Suehring, Rank: Intarweb Programmer, serial no: 
because the variable is unbound inside the function. 



Variable Naming Conventions 

One way to avoid a lot of the gotchas in PHP is to decide on, and to rigorously use, a set of variable nam- 
ing conventions for all of your code. In the frequent cases where variables will be assigned and used in 
widely separated places in the same script and even across scripts, such a set of standards will save lots of time 
referring back and forth. What conventions you decide on are less important than that you have some standard 
in the first place. That said, here are a few tips to help you decide what to do: 

■ A common mistake many new programmers make is thinking that variables must somehow be an 
abbreviation of the thing they represent. Remember, a variable is not an abbreviation, but rather 
a stand-in for some value that may change depending on circumstances or as a script executes. A 
longer, meaningful, and easy-to-remember variable name is better than a shorter variable name that 
is anybody's guess. 

■ Variable names that consist of multiple words strung together can be made more readable by using 
underscores (for example, $of f i ce_address) or initial capitalization ( $ 0 f f i ceAddress). There 
is some sense to the notion that the underscore solution can create confusion with function-naming 
conventions. Use what works best for you. 

■ In a more general sense, remember that you may not be the only person that has to read this code. 
You may get really excited about PHP and get involved in one of the many open source projects 
that use PHP. You may even start your own project (we'd be delighted to see that happen)! In either 
case, readable code will be a must, and good variable names are a foundation of producing read- 
able code. 



Function Problems 

Many problems having to do with function calls result in fatal errors, which means that PHP gives 
up on processing the rest of the script. 
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Symptom: Call to undefined function my_f unction () 

PHP is trying to call the function my_f unct i on ( ) , which has not been defined. This could be 
because you misspelled the name of a function (built-in or user-defined) or because you have simply 
omitted the function definition. If you use i ncl ude/ requi re files to load user-defined functions, 
make sure that you are loading the appropriate files. 

If the problem involves a fairly specialized, built-in function (for instance, it is related to XML or 
arbitrary-precision math), it may be that you did not enable the relevant function family when you 
installed or configured PHP. 

Symptom: Call to undefined function () 

In this case, PHP is trying to call a function and doesn't even know the function's name. This is 
invariably because you have code of the form $ my_f u n c t i o n ( ) , where the name of the function is 
itself a variable. Unless you are intentionally trying to exploit the variable-function-name feature of 
PHP, you probably accidentally put a $ in front of a sensible call to my_f uncti on ( ) . Because $my_ 
function is an unbound variable, PHP interprets it as the empty string — which is not the name of 
a defined function — and gives this uninformative error message. 

Symptom: Call to undefined function arrayO 

This problem has a cause that is similar to the cause of the previous problem, although it still baffled 
us completely the first time we ran into it. It can arise when you have code like the following: 

$my_amendments = arrayO; 
$my_amendments ( 5 ) = "the fifth"; 

Unless you look closely, this looks like an innocent pair of statements to create an array and then store 
something in that array, with the number 5 as a key. And yet PHP is telling us that a may ( ) is an 
unbound function, even though we know that it is a very standard built-in function. What's going on? 

The fault is actually with Line 2 above, rather than with Line 1. If we want to access an element of 
$my_amendments, the correct syntax is $my_amendments [5] , with square brackets. Instead, we 
used parentheses, which the parser interprets as an attempted function call. It takes what is imme- 
diately before the left parenthesis to be a function. Instead, what comes before the parenthesis is an 
array, which is not a function; PHP gives up on us, with this obscure complaint. 

Symptom: Cannot redeclare my_f unction () 

This is a simple one — somewhere in your code you have two definitions of my_f u n c t i o n ( ) , which 
PHP will not stand for. Make sure that you are not using i ncl ude to pull in the same file of function 
definitions more than once. Use i ncl ude_once or requi re_once to avoid seeing this error, with 
the caveat that, well, you won't see this error. Why might that be bad? It's conceivable that you could 
define two distinctly different functions and inadvertently give them the same name. This runs the 
risk of exposing your mistake at a somewhat inconvenient moment. 
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Symptom: Wrong parameter count 

The function named in the error message is being called with either fewer or more arguments than 
it is supposed to handle. In the case of more parameters you're okay, but if you use fewer parameters 
than is expected you will get an error. 



Math Problems 

The problems that follow are specific to math and the numerical data types. 

Symptom: Division-by-zero warning 

Somewhere in your code, you have a division operator where the denominator is zero. The most 
common cause of this is an unbound variable, as in: 

$numerator = 5; 

$ratio = $numerator / $denomi nator ; 

where $denomi nator is unbound. It's also possible, of course, that the legitimate result of a compu- 
tation is producing a zero denominator. In this case, the only thing to do is catch it with a test and 
do something reasonable if the test applies. See the following example: 

$numerator = 5; 

if ( i sset ( $denomi nator ) && $denomi nator != 0) 

$ratio = $numerator / $denomi nator ; 
else 

printCI'm sorry, Dave, I cannot do that<BR>"); 

Symptom: Unexpected arithmetic result 

Sometimes things just don't add up (or multiply up, or subtract up). If you are having this experi- 
ence, check any complex arithmetic expressions for unbound variables (which would act as zeros) 
and for precedence confusions. If you have any doubt about the precedence of operators, add (pos- 
sibly redundant) parentheses to make sure the grouping is as you intend. 

Symptom: NaN (or NAN) 

If you ever see this dreaded acronym, it means that some mathematical function you used has gone 
out of range or given up on its inputs. The value NAN stands for "Not a Number," and it has some 
special properties. Here's what happens if we try to take the arccosine of 45, even though arccosine 
is defined only when applied to numbers between -1.0 and 1.0: 

$ v a 1 ue = acos(45) ; 

print("acos result is $value<BR>"); 

print("The type is " . gettype ( $val ue ) . "<BR>"); 
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$val ue2 = $val ue + 5 ; 

pri nt ( " Deri ved result is $val ue<BR>" ) ; 

print("The type is " . gettype ( $ val ue2 ) . "<BR>"); 

if ($value == lvalue) 

printC'At least that much makes sense<BR>"); 
else 

print("Hey, value isn't even equal to i tsel f ! <BR> " ) ; 
The browser output looks like: 

acos result is NAN 
The type is double 
Derived result is NAN 
The type is double 

Hey, value isn't even equal to itself! 

Oddly enough, NAN is a number, at least in the sense that its PHP type in this example turns out to 
be double rather than string. It also infects other values with not-a-numberness when used in math 
expressions. (This behavior is a feature, not a bug, when used in very complex calculations that 
must be correct. It's better to have the whole value be tagged as untrustworthy than have one subex- 
pression be silently bogus.) Finally, any equality comparison that involves NAN will be false — NAN 
is neither less than, nor greater than, nor equal to any other number, including itself. It is always 
unequal (! =) to all numbers, including itself. (The NAN value is not a PHP-specific feature — it is 
part of the IEEE standard for floating-point arithmetic, which is implemented by the C functions 
that underlie PHP.) 

Because of the contagion of NAN values, this kind of problem can be difficult to debug. The best way 
to try to find the original offending NAN is with diagnostic print statements, especially because 
comparison tests will give counterintuitive results. You can explicitly test for NAN values using the 
built-in i s_n a n ( ) function, which returns TRUE if the number submitted is not a number or FALSE 
otherwise. In earlier versions (you aren't using an earlier version, are you?), you can cobble together 
your own function for NAN testing like this: 

function i s„nan ( $val ue ) 

{ 

return ( $val ue != lvalue); 

} 

It uses the weird comparison properties of NAN as a type checker. 



Timeouts 

Of course any download can occasionally time out before a complete page can be delivered. 
However, this shouldn't be happening frequently on your local development server! 
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The most interesting reason for a timeout is an infinite loop. These can be difficult to track down 
quickly, as in this example: 

//compute the factorial of 10 
$Fact = 1; 

for ($Index = 1; $Index <= 10; $index++) 
$Fact *= $Index; 

This code shows a nasty little collaboration between a loop and a case confusion — the lowercase 
$ i n d e x that is incremented has nothing to do with the $ I n d e x that is being tested, so the test will 
never become false. 



Summary 

In Table 10-1, we summarize the gotchas in this chapter by mapping symptoms to possible causes. 
We also offer some suggestions on how to fix the most common problems. 



TABLE 10-1 



From Symptoms to Causes 


Symptom 


Possible Causes 


Advice 


(New installation) 
Text of file 
displayed in 
browser window 


The PHP engine is not being invoked, 
possibly because you are opening it 
via the local filesystem rather than as a 
request to your server. 


Make sure that your request is to the web 
server, either via localhost ( http : / / 
localhost/[path])if testing on the 
server machine, or by the full UR1 (www . 
exampl e . com/ [path] ) . 


(New installation) 
PHP blocks 
showing up as 
text, or browser 
prompts you to 
save file 


PHP is not being invoked properly. 
Your web server may not be set up 
to map the right file extensions (for 
example, . php) to the PHP engine, 
or there may be a problem with the 
location or contents of php . i ni . 


Check your web server configuration, 
and the PHP init file (php . i ni ). 


(New installation) 
Server or host 
not found/ 
Page cannot be 
displayed 


Often due to Internet/DNS/web-server 
configuration problems, rather than PHP. 


Try loading a pure HTM1 file with a file 
extension you have not set up for PHP 
(for example, . html ) to rule out PHP 
problems. 


Totally blank page 


Usually due to PHP syntax errors. 


Use d i e ( ) to determine the location of 



the syntax error. 
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Symptom 


Possible Causes 


Advice 


PHP code 
showing up in 
browser window 


If the PHP engine is installed and 
functioning properly, this is usually 
due to a missing PHP start tag or 
misconfigured web server. 


Check start and end tags and make sure 
that any i ncl ude files of PHP code 
have correct tags at beginning and end 
also check web server functionality with 
a basic PHP page. 


Parse error 
message 


A variety of causes, including missing 
semicolons, variables without a 
$, unescaped quotation marks, 
unclosed quotation marks, brackets, 
or parentheses, and HTML being 
interpreted as PHP. 


Locate the line with the parse error in the 
PHP file, and look for one of the causes 
in that line or the lines immediately 
preceding it. If the "error" is on the final 
line of the file, look for an unclosed 
quote, parenthesis, or bracket, possibly 
much earlier in the file. 


I ncl ude 
warning 


For one reason or another, PHP was 
not able to load a file named in an 
include statement. 


Check that the file actually exists, the 
spelling of the filename, the pathname, 
and (on Unix systems) the case of the 
name. Also make sure that the file 
permissions allow the file to be read. 


Variable value 
not showing up 
in print string 


The variable has not been assigned, 
and so its value in a printed string is the 
empty string. 


Check that you are assigning the variable 
before the print statement and compare 
spelling and case (capitalization). Make 
sure that you are not embedding any 
objects or multidimensional arrays in 
quoted strings. You can also use the 
statement error- report! ng( 15) to tell 
PHP to warn about any unbound variables. 


Numerical 
variable 
unexpectedly 
zero 


Often due to the variable never having 
been assigned. 


(See preceding.) 


Variable value 
is valid, but 
unexpected. 


Often due to variable having been 
unexpectedly overwritten. 


Use good variable names; search through 
all included files for variable name. 


Call to undefined 
function my_ 

f uncti on ( ) 


Function my_f uncti on ( ) is being 
called without having been defined 
first. 


If you are trying to call a function of 
your own, check that the definition 
(or inclusion of the file containing the 
definition) is before the use. If you are 
trying to call a built-in function, check 
the spelling. If it is correct, investigate 
whether that "family" of functions was 
included when you configured PHP (for 
example, either all the XML functions 
will work, or none will). 



continued 
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(continued) 




Symptom 


Possible Causes 


Advice 


Call to undefined 

function ( ) 


An expression of the form $my_ 
f uncti on () is being evaluated, and 
$my_f uncti on is not bound to the 
name of a defined function. 


If you intend to use the variable-function 
feature, then add (or correct) the 
assignment of $ my_f unction. If you 
are just trying to call my _f uncti on ( ), 
remove the $. 


Call to undefined 
function 

array ( ) 


You probably have an expression of 
the form $a rray_var_name ( 3 ), 
when what you want is $array_var_ 
n a mp T 3 1 


Decide whether you want an array 
expression or a function call — if the 
former, then change parentheses to 

Qniisrp KrarkptQ 


Cannot 
redeclare my_ 

f uncti on ( ) 


The function my_f uncti on ( ) 
is being defined twice in a page's 
execution. 


Look for double definitions of my„ 
f uncti on in the PHP file, or double- 
inclusions of the file that defines it. 


Wrong parameter 
count 


The named function (usually a built-in 
function) is being called with an 
incorrect number of arguments. 


Compare the function call to the 
definition in the online PHP manual 
(www .php.net) 


Division-by-zero 
warning 


A / operator has a right-hand argument 
of zero. Can be due to an unbound 
variable in the denominator. 


Assign the unbound variable if that's the 
cause. If the desired logic could actually 
result in zero denominators, install a test 
to catch that case. 


Unexpected 
arithmetic result 


Frequently due to an unbound variable 
in an arithmetic expression. 


Check for unbound variables (see 
preceding), and make sure that 
arithmetic expressions are parenthesized 
appropriately. 


NAN value 


A built-in math function is being given 
inputs outside its acceptable range. 
If that function's results are used in 
arithmetic, the results are also NAN. 


Trace backward from the NAN value 
to function calls that contribute to 
its computation. Test with print 
statements, or test for values that fail to 
be self-equal (a diagnostic for NAN). 
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Introducing Databases 
and MySQL 



Databases and PHP go together like cake and ice cream, Trinidad 
and Tobago, green eggs and ham — you get the picture. 

After all, what's the Web about? Making vast stores of informa- 
tion available to a more or less wide public, that's what. Not that there 
aren't small brochureware sites galore, but the bigger and more frequently 
updated the data source, the more comparative value is provided by the 
Web over other media. 

Perhaps the single greatest advantage of PHP over similar products is the 
unsurpassed choice and ease of database connectivity it offers. As detailed 
in the "Choosing a Database" section of this chapter, PHP supports native 
connections to a number of the most popular database server types, open 
source and commercial alike. Almost any database that will open its appli- 
cation programming interface (API) to the public seems to be included 
eventually. For any unsupported databases, there's generic ODBC (Open 
Database Connectivity) support. 



What Is a Database? 

A database is a collection of data. The term database usually indicates that 
the collection of data is stored on a computer. Regardless, it's the databases 
that are on computers that I'll concentrate on in this book. 

Databases implemented through a computer are created within software. 
That software, commonly known as a database application, controls how 
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the actual data is stored and retrieved. Some database applications include Microsoft Access and 
OpenOffice. org's Base. Sometimes, databases are stored in a central location and managed by a data- 
base server. A database server is a database application built with multiple users in mind. 

Most of the time when programming PHP you'll be accessing a database server. Some database servers 
include PostgreSQL, MySQL, Microsoft's SQL Server, and the Oracle suite of databases. You may also 
see database servers called RDBMS, which is an acronym for relational database management system. 

Database servers usually have one or more distinct APIs for programmatically creating, accessing, 
managing, searching, and replicating the data they hold. It is through the API that you connect to 
and work with data stored in database servers when using PHP. 

There is no requirement that an RDBMS be used to store data. Other data stores can be used such as 
a flat file or a table known as a hash table. These are perfectly fine for some applications, especially 
smaller applications; however, for larger applications or applications that require optimal speed for 
large data stores, an RDBMS is a requirement. 



Why a Database? 

If you're going to the trouble to use PHP at all, you're likely to need a database sooner or later — 
probably sooner. Even for something small, like a personal blog, you want to think hard about the 
advantages of using a database instead of static pages or included text files. 

Maintainability and scalability 

Having PHP assemble your pages on the fly from a template and a database is an addictive experi- 
ence. Once you enjoy it, you'll never go back to managing a static HTML site of any size. For the 
effort of programming one page, you can produce an infinite number of uniform pages. Change one, 
and you've changed them all. 

There are now web sites with hundreds of thousands of separate pages — you can rest assured that 
no one is maintaining them all by hand. If you have a web site that may eventually grow to more 
than a few dozen pages, you should think about moving to a database sooner rather than later. 

Portability 

Because a database is an application rather than a part of the operating system, you can easily trans- 
fer its structure and contents from one machine to another or (in certain cases) even from one plat- 
form to another. This is especially valuable for contractors, who may develop a project without being 
able to control the environment in which it will eventually be deployed — they can deliver a pack- 
age of PHP plus a MySQL database schema dump. 
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Avoiding awkward programming 

Certain things can be done with PHP but probably shouldn't, because they entail ugly or risky pro- 
gramming moves. 

Say that you happen to be the commander of the starship Enterprise and are keeping a captain's 
log. Each log entry is contained in a text file identified by its unique stardate, which is plugged into 
a template by PHP — but hey, you're a busy spaceman with whole galaxies to explore; you don't 
always have time to write in your log every day. You want to put automatically generated Next and 
Previous links on each page for those who wish to read in straight chronological order. It's pretty 
easy to use PHP to find the previous stardated entry, but any attempt to locate the next entry can 
quickly become an infinite loop — because it's easier to prove something does exist than that it 
doesn't. On the other hand, if you put your log data in a database, the whole job becomes trivial. 
The database will tell you which is the latest entry at any given moment. 

There are other types of programming tasks that a database is highly optimized to do, and given 
the option, you should take advantage of it to perform these chores. For instance, you should avoid 
sorting data sets on the PHP side in favor of writing queries so the data is returned presorted. We 
discuss these efficiency issues in greater detail in Chapter 18. 

Searching 

Although it's possible to search multiple text files for strings (especially on Unix platforms), it's not 
something most web developers will want to do often. After you search a few hundred files, the task 
becomes slow and hard to manage. Databases exist to make searching easy. With a single command, 
you can find anything from one ID number to a large text block to a JPEG-format image. 

In some cases, information attains value only when put into a searchable database. For instance, 
relatively few people would want to read a long text list of movie directors and their films, but 
many might occasionally want to search a database of that information. You could argue that it's the 
searchability, as much as the information itself, that creates the value here. 



PHP-Supported Databases 

PHP Data Objects (PDO) was introduced back with the 5.1 release of PHP. PDO creates a consistent 
abstracted interface to database servers and data. PHP offers several database-specific drivers for 
both PDO and non-PDO access. The PHP web site contains a list with the latest information about 
databases that can be integrated along with the PDO abstraction layer and other abstraction layers. 
See www .php.net/pdo for more information. 
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Our Focus; MySQL 



MySQL, (officially pronounced my- S - Q - L and not "mysequel"), is an incredibly popular and powerful 
RDBMS. MySQL provides one of the letters in the ubiquitous acronym "LAMP," which is an abbreviation 
for Linux, Apache, MySQL, PHP/Perl/Python. MySQL has become so popular for several reasons. First, 
MySQL is free (as in price), although the licensing has changed (discussed later). Second, MySQL is also 
stable, meaning that it's not prone to crashing even under load. Third, MySQL is lightweight, meaning 
that it doesn't require many resources to install or run. Fourth, MySQL is fast and easy to use. Finally, 
MySQL is powerful, with all of the features required for web applications. 

MySQL AB, which is the company behind MySQL (owned by Sun), changed the licensing for MySQL 
relatively recently. In the latest iteration as of this writing, MySQL offers a product called MySQL 
Server Community Edition, which is essentially the same as the MySQL Enterprise Server, but is 
lacking official MySQL support and some graphical user interface (GUI) tools. If your organization 
needs an officially supported product, where you can call for assistance with the database server at 
any time, then MySQL Enterprise is for you. MySQL AB's support is excellent; it's not unheard of to 
get responses from developers themselves. Otherwise, the MySQL Server Community Edition is your 
choice. For more information on the differences between the two versions, see www . my sql .com/ 
products/whi ch-edi ti on . html . 

I'll be concentrating on the MySQL Server Community Edition in this book, and the next chapter 
will show you how to obtain and install MySQL. 



Summary 



The great advantage of the Web is its capability to make large quantities of information publicly 
available quickly and cheaply. This functionality has been tremendously enhanced by the recent 
increase in availability of inexpensive, reliable databases. 

PHP supports several types of databases, including flat-file, hash, and relational databases. Most 
large web sites (and even small sites, too) use some sort of relational database management system 
(RDBMS). MySQL is a common choice among PHP developers. MySQL is not only free but also light- 
weight, stable, and full of features necessary for both online and offline applications. 
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Before jumping into MySQL installation you need to get the software. 
MySQL's database server can be downloaded from MySQL's web site 
at www . my sql . com. As of this writing, the free Community Edition 
server feels somewhat hidden on the web site. Therefore, with the caveat 
that the URL may change on a whim by the time you read this text, the 
download section for MySQL is currently located at http://dev.mysq! 
. com/downl oads. However, realize that most distributions of Linux 
include their own MySQL server package. 



Obtaining MySQL 

I strongly recommend using the MySQL server package directly from your 
Linux distribution rather than downloading from MySQL AB unless you 
have a very specific reason for using a different version. If you can't think 
what one of those specific reasons might be, then you probably don't have 
one, and you therefore should use the MySQL server available with your 
distribution. 



Installing MySQL on Linux 

There are several distributions upon which you might find yourself install- 
ing MySQL. It's always a challenge choosing which distributions to cover. 
No matter which ones we decide to cover there will always be someone 
installing on another distribution. 



IN THIS CHAPTER 



Obtaining MySQL 
Installing MySQL on Linux 
Installing MySQL on Windows 
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In this section I'll examine MySQL installation on Debian, CentOS, and Ubuntu. Additionally, 
I'll demonstrate compiling MySQL from source for those who don't have a MySQL server package 
available with their distribution. It should be noted that because MySQL 6 is so new it may not be 
available as a package in your distribution. If this is the case, I recommend sticking with the latest 
MySQL available for your distribution. For the most part, this book will use functions available in 
MySQL 5 and later, so MySQL 6 isn't a requirement. Where MySQL 6 is required, a special note will 
be shown. 

Installing MySQL Server on Debian and Ubuntu 

Debian's dpkg and apt installation and package management tools make installation of MySQL (and 
everything else for that matter) incredibly easy. Debian is a system administrator's dream because 
it's so stable, package installation is so easy, and the packages are maintained and configured with 
excellent defaults. But enough evangelizing; installation of MySQL server on Debian requires super- 
user privileges and is accomplished simply by running a pt - get: 

apt-get install mysql -server 

Of course, that assumes that you have correctly configured sources in /etc/apt/sources . 1 i st. 
For more information on APT and configuration of the sources. list file, see www .debian.org/ 
doc/manuals/apt-howto/ch-basico.en.html. Debian's package management system will 
install and configure any necessary prerequisites for you. 

Debian separates MySQL into its components such as server, client, and libraries. Therefore, in order 
to use MySQL and PHP together, you should install the php5-mysql package: 

apt-get install php5-mysql 

As you can see by that installation command, the PHP5 version of the interface is being installed. 
That is the latest version available as of this writing. 

Finally, you'll likely also want to install the MySQL command-line interface (CLI), which is accom- 
plished by installing the mysql-client package: 

apt-get install mysql-client 

MySQL will now be installed and ready to use on your Debian server. However, by default the 
MySQL server won't listen on anything by localhost. To change this, edit /etc/ mysql / my. cnf and 
comment out the skip-networking line with a pound sign or hash mark (#), so it looks like this: 

#ski p-networki ng 

Now restart the MySQL server by typing this command: 

/etc/i ni t . d/mysql restart 
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Installing MySQL on Microsoft Windows 

MySQL installation on Windows is much, much easier than it used to be thanks to fully automated 
installers 

Installing MySQL on Windows 

Default installation on any version of Windows is now much easier than it used to be, as MySQL 
now comes neatly packaged with a native Windows installer. Simply download the installer package, 
usually an msi, and run it. This will walk you through the trivial process and by default will install 
everything under C:\Program FilesXMySQL, which is probably as good a place as any. 

The MySQL installer will attempt to install itself as a service, which means you need Administrator 
rights on the computer upon which MySQL is being installed. Part of the installation process will 
configure the MySQL server. During this portion of the installation, you can configure things like 
the root password, the port on which MySQL will listen, and whether to include the MySQL utilities 
in the Windows path (I recommend that you do so). 

The Windows install is now so simplified that for most cases you can simply click "Next" to con- 
tinue and, where you have an exception, refer to the online manual for MySQL at www . mysql . com. 



Summary 

This chapter examined installation of MySQL on Linux and Windows. The Linux installation var- 
ies somewhat depending on the flavor of Linux on which MySQL is being installed. However, the 
Windows installation has been greatly refined and reduced to simply clicking through the installa- 
tion and receiving a fully functional yet incredibly powerful database system. The online documen- 
tation for MySQL is available for assistance with installation issues, should they arise. 
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This chapter is a basic introduction to SQL databases in which we 
discuss standards, database design, Data Manipulation Language, 
Data Definition Language, and database security procedures com- 
mon to all SQL databases. 

This chapter is in no way a comprehensive guide to SQL or to 
any particular SQL database. To go beyond the simplest com- 
mon features, you will need to consult your particular manufacturer's docu- 
mentation or specific books. You will also want to look at documentation and 
books relating to your specific SQL database. 



IN THIS CHAPTER 



Relational databases and SQL 
SQL standards 
The workhorses of SQL 
Database design 
Privileges and security 



Relational Databases and SQL 

SQL is the language of relational databases. A simple query like a one-table 
SELECT will be more or less the same whether you're using a tiny database 
like mSQL or an expensive behemoth like Oracle. 

The big advantage for you, the web developer, is that, after you learn SQL, 
you will be able to interact with numerous databases across all platforms 
without a steep retraining curve. Just imagine how horrible life would be if 
Oracle, MySQL, and SQL Server all had entirely different sets of commands 
for putting data in and getting data out of their stores — as if Oracle used 
SELECT to ask for data sets, MySQL used VALJ (the developers are Swedish, 
you know), and SQL Server used FIND IT IN THIS TABLE (to better match 
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the vocabulary of Windows). SQL is the common vocabulary and syntax that will save you from this 
nightmare. There are differences among products, and in their implementations of the SQL standard 
and the extensions they each define to that standard, but it's better to have 80 percent in common and 
20 percent different than the other way around. 



SQL Standards 

According to Andrew Taylor, original inventor of SQL, SQL does not stand for Structured Query 
Language (or anything else for that matter). But for the rest of the world, it does now. As you would 
expect from the (non-) title, SQL represents a stricter and more general method of data storage than 
the previous standard of flat-file DBM-style databases. 

SQL is a standard under both the American National Standards Institute (ANSI) and the Equipment 
Managers Council of America (ECMA); both are international standards-maintenance organizations. 
You can read the standards on payment of a fee to these organizations: 

■ www . ans i .org 

■ www.ecma.org 

However, within the general guidelines of the standard there are considerable differences among the 
products of individual companies and open source database development organizations. The past 
few years, for instance, have seen the rapid growth of so-called object-relational databases, as well as 
of SQL products specifically slanted toward the web market. 

The key to choosing a database is to be selfish, or at least supremely self-centered. You will see 
plenty of unusually virulent postings out there opining that a certain advanced database fea- 
ture (like triggers or cross joins) is a "must," and any SQL installation without this feature hardly 
deserves the name. Take this stuff with a grain of salt. It's far better to make a blind shopping list of 
functions you need in order of importance and then go out looking for the product that best meets 
your requirements. 

That said, a good deal of SQL really is pretty standardized. You will be using a few SQL statements 
over and over and over, no matter which specific product you choose to deploy. 



The Workhorses of SQL 

The basic logical structure of a SQL database is very simple. A given SQL installation can usually 
contain multiple databases — for instance, one for customer data and one for product data. (It's 
problematic that both the SQL server itself and the collections of tables within it are commonly 
referred to by the term database — but what can you do?) Each database contains a number of 
tables. Each table is made up of carefully defined columns, and every entry can be thought of as an 
added record or row. (It's not really a row, but this is a concept so stuck in our visualization that we 
may as well go with it.) 
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Four so-called data manipulation statements are supported by every SQL server and will constitute an 
extremely high percentage of all the things you'll want to do with a relational database. These four 
horsemen of the database are SELECT, INSERT, UPDATE, and DELETE. These commands are your 
friends and helpmates; get comfy with them, and they will serve you well. 

The thing to remember about these four SQL statements is that they manipulate only database val- 
ues, not the structure of the database itself. In other words, you can use these commands to add data 
but not to make a database; you can get rid of every piece of data in a database, but the shell will still 
be there — so, for instance, you wouldn't be able to name another database on the same server with 
the same name. If you want to add or get rid of columns, blow away entire databases as if they never 
existed, or make up new databases, you need to use other commands such as DROP, ALTER, and 
CREATE. We discuss these in the "Database Design" section later in this chapter. 

FTp™ f ^ no ' e on ^Q*" s ty' e: Many SQL queries that you see are written in one long line of code — 

which becomes totally illegible once you're dealing with more than four or five fields. A 
very accomplished PL/SQL programmer of our acquaintance recommends that you break up every SQL 
statement into as many lines as you need for maximum legibility. He also does not shy away from using 
indentation in a SQL query with many variables. (SQL queries are usually quite whitespace insensitive.) 
He has years of experience working on big Oracle installations, and his recommendations actually are 
very helpful — so that is the style we try to use in this book. 

SELECT 

S E L ECT is the main command you need to get information out of a SQL database. The basic syntax 
is extremely simple: 

SELECT fieldl, field2, f i e 1 d 3 
FROM table 

That's no harder than asking your coworker to get you last month's sales records from the file cabi- 
net in the hallway. 

In some cases, you'll want to ask for entire records instead of picking out individual pieces of infor- 
mation. This practice is generally frowned upon, but it is still widely used and, therefore, we need to 
mention it. A whole record is called for by using the wildcard (asterisk) symbol: 

SELECT * 
FROM mytable 

Selecting Certain Records 

The previous two examples show how to retrieve all rows from the table. It's not all that common 
to do this in the real world, which is where the WHERE clause comes in. The WHERE clause places a 
condition on the SELECT statement that causes only those rows matching the WHERE clause to be 
returned in the result set. For example: 

SELECT * 
FROM mytable 
WHERE ID < 100; 
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This example retrieves all fields from the table mytabl e where the ID column value is less than 
the integer 100. WHERE clauses can get quite complex, and, frequently, multiple conditions are used 
together with the AND keyword. 

Joins 

Joins are one of the main useful features of SQL. 

A SELECT statement on a single table without joins might be visualized as being something like a 
row in a spreadsheet. But an SQL database is by definition relational. To understand the philosophy 
behind the relational database concept, you have to think back to some occasion on which you were 
forced to fill out a whole bunch of forms — such as applying for a loan, visiting a doctor's office for 
the first time, or dealing with some kind of governmental formality. (If you've never had this experi- 
ence, it's because you're young enough to have lived entirely in a world of relational databases.) As 
you were writing down your name, address, phone, and Social Security number for the 15 th time, 
you probably thought, "Why can't I just write my address down once, and then they could just look 
it up on a need-to-know basis?" That's exactly the concept behind a relational database. 

The way a relational database differs from paper forms is the main identifier. Humans do well with 
text and prefer to categorize by textual identifiers such as names. If a dentist's office or auto body 
shop stored its paper files in numerical order, it would be difficult for anyone to lay his hands on 
John Johnson's forms when John next required service. Frankly, most paper file users these days ask 
for your Social Security number as a backup — it works solely to differentiate you from other people 
in their files with exactly the same first, last, and middle names. 

Databases, on the other hand, work well with integers. You'll frequently use integer values to create 
unique identifiers or IDs within a database table. This field or column is then called a primary key, 
which indicates that each value in that column will be unique and that the rows within that column 
will always have a value in the primary key field. Because primary keys are unique by nature, a 
database needs only one to identify a person, place, or thing uniquely — no matter how many tables 
refer to that piece of information. 

So instead of needing to repeat information several times, like this: 

Name: John Johnson 
SS#: 123-45-6789 

Name: John Johnson 

Fears: Cats, Friday the 13th, Flying 

Name: Jane Jones 
SS#: 987-65-4321 

Name: Jane Jones 
Fears: Heights, Flying 

with a relational database you can write down each piece of information just once and then relate it 
to each other piece using integers, as shown in Tables 13-1 to 13-3. 
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TABLE 13-1 



People 


Person ID 


Name 


SS# 




1 


John Johnson 


998-00-9889 




2 


Jane Jones 


987-65-4321 





3 Aloysius Snuffleupagus 987-65-4329 



TABLE 13-2 



Fears 


FearlD 


Fear 




1 


Black cats 




2 


Friday the 13th 




3 


Peanut butter sticking 


; to the roof of your mouth 


4 


Heights 





5 Flying 



TABLE 13-3 



Person_Fear 


ID 


PersonID 


FearlD 


1 


1 


1 


2 


1 


2 


3 


1 


5 


4 


2 


4 


5 


2 


5 



This is clearly a neater and faster (for a database) way to store this information. But when you need 
to pull out the data into a human-readable form, there's a problem: You have to get and correlate 
information from more than one database. That's the job of a join. 
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To find out what phobias were suffered by Ms. Jones, you could first look up her personal unique ID: 

SELECT PersonID 
FROM People 

WHERE Name = 'Jane Jones'; 

that returns the unique integer 2. Then you can define another SELECT statement using that 
information: 

SELECT FearlD 
FROM Person_Fear 
WHERE PersonID = 2; 

You get the values 4 and 5 back, which you can use in a third query: 

SELECT Fear 
FROM Fears 

WHERE FearlD = 4 OR FearlD = 5; 

This returns the values Heights and Flying. We should make it clear that there is nothing 
inherently incorrect about doing it this way, as long as any performance loss is within parameters 
acceptable to you. 

Alternatively, you can perform a join, which returns the same information in a single SELECT 
statement: 

SELECT Fears. Fear 

FROM Fears, Person_Fear, People 

WHERE Fears. FearlD = Person_Fea r . Fea r I D 

AND Person_Fear. PersonID = Peopl e . PersonID 

AND People. Name = 'Jane Jones'; 

An alternate syntax for this join is: 
SELECT Fears. Fear 

FROM (Fears INNER JOIN Person_Fear ON FearlD INNER JOIN People on 
PersonID) 

WHERE People. Name = 'Jane Jones'; 

As you can see, you need only know one single piece of information to be able to get all the data in 
the database about that subject using joins. In effect, a join makes two or more tables into one for 
purposes of searching for a particular piece of information. 

Joins come in several different flavors. The one in the preceding example is called an inner join, 
which is the most common and restrictive type. Another common type is the outer join. This is used 
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to return a list of all fears even if they do not have people attached to them. In this example, we are 
using a left outer join (also known as a natural join): 

SELECT Fear 

FROM Fears LEFT JOIN People ON PersonID; 

Fears that have people attached to them would appear in the data set multiple times, but fears with- 
out people would each appear once. 

You can also get a list of all people even if they do not have fears attached to them, using a right outer join: 
SELECT Name 

FROM Fears RIGHT JOIN People ON PersonID; 

Again, the fears that are actually attached to people appear multiple times, whereas the fears that are not 
suffered by any people still show up once in the data set. As you can see, left and right outer joins differ 
in which of the two tables you want the actual data set from: the first (left) or the second (right). Because 
you can switch them around at will, many people consistently use the left outer join for all outer joins. 

/-v ' '■ f; ' Ask yourself whether you really need to be using outer joins. Because outer joins require less 
precision to format, inexperienced SQL users often perform an outer join and then filter the 
results in the code layer. This is wasteful and slow. Outer joins are all about the NULL values, which are not 
easily returned by inner joins. An example of a good use for an outer join is a report where you want to see 
which of your registered users had and had not downloaded your latest software product and how many 
times they had downloaded. If you are not in this situation, learn to use inner joins instead. 

Finally, there is something known as the self -join, which is a more advanced technique and won't 
really make a lot of sense with the example data set. It's often used with denormalized data, which 
means data that deliberately bends the rules of good SQL design (for example, never repeating any 
data point) for performance reasons (for example, to reduce the number of complex multitable joins). 

If you need to make complex and frequent joins, this may constrain the brand of SQL database you 
can use, because not all of them support every type of join. 

Subselects 

Before we leave the realm of SELECT statements, we should mention the subselect. This is a statement 
such as: 

SELECT phone_number 
FROM table 

WHERE name = (SELECT name FROM table2 WHERE ID = 1); 

Subselects are more of a convenience than a necessity. They can be very handy if you're working 
with enormous batches of data, but you can get the same result with two simpler S E LECTs. The sub- 
select is faster if the subselect clause returns a large data set, but there are cases where two selects 
will not appreciably affect performance. 
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INSERT 

Of course, no matter how many SELECT queries you write, all is for naught if you haven't put any 
information in the database to begin with. The command you need to put new data into a database 
is INSERT. The basic syntax is: 

INSERT INTO table (coll, col2, col3) VALUES(vall, val2, va!3); 

Obviously, the columns and their values need to match up; if you mix up your array items, noth- 
ing good will happen. If some of the rows will not have values for some of the fields, you will need 
to use an empty, null, or auto-incremented value — and, at a deeper level, you may need to have 
ensured beforehand that fields can be nullable or auto-incrementable. If this is not possible, you 
should simply leave out any columns you wish to default to an empty value in an I NSERT statement. 

A twist on the basic INSERT is the INSERT INTO ... SELECT. This just means you can INSERT the 
results of a SELECT statement: 

INSERT INTO customerCbi rthmonth , birthflower, birthstone) SELECT * FROM 
bi rthday_i nf o WHERE birthmonth = $bi rthmonth ; 

Not every SQL server has this capability. Also, you need to be careful with this command 
because you can cause problems for yourself quite easily — for instance you can overwrite data 
or experience locking issues. In general, it's not a good idea to select from the same database 
you're inserting into. 



UPDATE 

U PDATE is used to edit information already in the database, without deleting any rows. In other 
words, you can selectively change some information without having to delete an entire old record 
and insert a new one. The syntax is: 

UPDATE table 

SET f i el dl= 'vail' , f i el d2= ' val 2 ' , f i el d3= 1 val 3 ' 
WHERE condition; 

The conditional statement is just like a SELECT condition, such as WHERE I D > 1 5 AND ID<21or 
WHERE gender= ' F ' . 



DELETE 

DELETE is pretty self-explanatory: You use it to delete the contents of one or more fields perma- 
nently from the database. The syntax is: 

DELETE datapoint 
FROM table 
WHERE condition; 
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The most important thing to remember is the condition — if you don't set one, you will delete 
every entry in the specified columns from the database, without a confirmation or a second chance 
in many cases! 

A 0'Vt : ' Let us reemphasize: you must remember to use a condition every single time you UPDATE 

S^mJUmmm^M or DELETE! If you do not, every single row in the table will experience the same altera- 
tion or deletion. Even very experienced programmers have forgotten to include the condition, to their 
vast professional embarrassment. You should also give a good deal of thought to restricting database 
permissions so the minimum number of people can perform these potentially dangerous operations. I'll 
usually jump ahead and write the beginnings of the WHERE condition before filling out the rest of the 
DELETE FROM portion of the statement, just to make sure I don't inadvertently delete the entire table's 
worth of data. Another tip is to use the limit keyword within the DELETE statement so as only to 
delete the number of rows specified in the limit. 



Database Design 

As should be obvious from the previous section, learning to use a SQL database isn't exactly rocket 
science — you can get a lot done with just a few simple commands. The hard part is designing the 
database in the first place and, of course, operating it in the real world over time. Not every web 
developer will be asked to design a schema in a professional context, but it never hurts to know how. 

At the most fundamental level, database design can be broken down into the following mantra: 

One to one, 
One to many, 
Many to many, 
Many to one; 

And always use a unique ID. 

An example of one-to-one data for Americans is the Social Security number (other nations probably 
have similar identification cards with unique numbers). Each U.S. citizen has only one unique iden- 
tifier; it is, in fact, a crime to use the Social Security number of another individual or apply for more 
than one number. Database designers seize upon truly unique identifiers such as this because almost 
every other piece of personal information is subject to change — which accounts for the large num- 
ber of businesses who inappropriately use the Social Security number for identification purposes. 

One-to-many data and many-to-one axe the same, differing only in how the columns are placed in a 
database. An example of one-to-many data comes from the medical realm: patients to visits. Each 
patient will always be a discrete individual but may have any number of visits to the doctor. If you 
designed the table to represent visits to patients, it would instantly become many-to-one data. 

Finally, many-to-many data is well represented by the relationship of authors to books. Not only can 
a given book have multiple authors, but each author may have written or coauthored many books. 
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This is not a matrix of relationships that would be easy to represent efficiently in a spreadsheet, but 
it is precisely this category of data at which relational databases most excel. 

Every data relationship falls into one of these categories. As a database designer, it's your job to 
decide which one of these represents what you need to know in the way you need to know it. 

This is not as trivial as it sounds. Imagine that you want to develop a database of movie information. 
One decision you might have to make is whether movie and title are in a one-to-one relationship 
with each other, or whether enough films have alternate titles to merit an alternate title field or even 
a one-to-many representation. There's no right answer here — the decision depends on exactly how 
the information will be used, how large the database will be, if the extra resources required to main- 
tain a more precise data structure are worth the cost, and whether there's a better-than-even chance 
that today's tangential trivia will become tomorrow's crucial discovery. Some people may be sur- 
prised to learn that archiving information can be as much about ruthless excluding as about careful 
hoarding. As historians say, history is about forgetting as much as it is about remembering. 

The simplest relationship is the one-to-one because you can group all these fields into a single table 
that can be searched more quickly. For instance, a table holding customer information might con- 
tain the following fields: 

Customer ID 
Customer name 
Administrative contact 
Technical contact 

The hardest thing about the one-to-one relationship is definitively deciding that you will never need 
to make it into a one-to-many relationship. For instance, what if your biggest customer decides it 
wants to designate two technical contacts? 

As soon as you have a one-to-many, many-to-one, or many-to-many relationship, you're looking at 
going from a single table to multiple tables: one each for the main variables and one stating the rela- 
tionship. Tables 13-4 through 13-6 show a common example of a many-to-many relationship: 



TABLE 13-4 



Customer 


Customer_id 


Name 




1 


Acme Bread 




2 


Baker Construction 




3 


Coolee Dam 
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TABLE 13-5 



Interactions 


lnteraction_id 


Type 




1 


Phone-support incident 




2 


On-site incident 




3 


Written complaint 




4 


Phone complaint 




5 


Kudo 










TABLE 13-6 






Customer-Interaction 


Customer- 
interaction_id 


Customer_id lnteraction_id 




1 


1 1 




2 


3 5 




3 


2 4 




4 


2 3 




5 


1 2 





After you've decided on a database design, the mechanical details of constructing the database are 
minimal. The main data structure statements of SQL are CREATE, ALTER, and DROP. 

CREATE is used to make a completely new table. All the work is in defining the columns of each 
table. First, you declare the name of the table, and then you must detail the specific data types of 
that table's columns in what is called a create definition. A CREATE statement will take this form: 

CREATE TABLE tablename ( 

id_col INT NOT NULL AUTO_INCREMENT PRIMARY KEY, 
coll TEXT NULL INDEX, 
co!2 DATE NOT NULL 
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Different SQL Servers have slightly different data types and definition options, so the syntax of one 
may not transfer exactly to another. For instance, Oracle databases do not auto -increment; to get a 
new value, you must generally call a function. 

DROP can be used to completely delete a table and all its associated data. It's not the most subtle 
command: 

DROP TABLE tablename; 
Obviously, you need to be very careful with this statement. 

ALTER is the way to change a table's structure. You simply indicate which table you're changing and 
redefine its specs. Again, SQL products differ in functionality here. The ALTER statement usually 
takes this form: 

ALTER TABLE table RENAME AS new_table; 

ALTER TABLE new_table ADD COLUMN col3 VARCHAR(50); 

ALTER TABLE new_table DROP COLUMN col2; 



Privileges and Security 

As we state in Chapter 28, security online is analogous to security in the real world. Any cop will 
tell you that you cannot make your home absolutely crime-proof. A more realistic goal is to increase 
the difficulty and risk to a level where a large percentage of intruders will choose to go to an easier 
target down the block. 

Setting database permissions 

The most fundamental rule of database use (of any computer security, really) is to give each user or 
group only the minimum permissions necessary to do what needs to be done. Besides the threat 
of malicious/experimental outsiders, setting the correct permissions can protect you from your 
coworkers and yourself. Insiders have been known to cause massive problems through disgruntle - 
ment, ignorance, momentary brain freeze, or a combination of motives. You do not want to have to 
cope with the consequences of a fired employee's parting shot or a new intern trying out the DROP 
database command just to see what happens. 

A typical database permissions package might be something like: 

■ Web visitor: SELECT only 

■ Contributor: SELECT, INSERT, and maybe UPDATE 

■ Editor: SELECT, INSERT, UPDATE, and maybe DELETE and maybe GRANT 

■ Database Administrator: SELECT, INSERT, UPDATE, DELETE, GRANT, and DROP 
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DROP in particular is the nuclear bomb of SQL because it allows you to blow away an entire table 
or database with a single command. Someone's got to have the ability, but heavy lies the tiara of 
responsibility on the head of the root database user. Use the power wisely, grasshopper. 

In many databases, including MySQL, passwords are encrypted using a different algorithm from 
system passwords (and, of course, they are typically stored in entirely different locations). Even if 
one is cracked, the other is not necessarily vulnerable. This assumes that you take the time to set 
permissions correctly, pick good passwords, and usually employ a special command to insert user- 
names and passwords correctly into the grant table (as opposed to inserting them like other data). 



CAUTION 



Database usernames and passwords should not be identical to system usernames and 
passwords. 



r' y r ~ C'Tj<> p p Chapter 14 covers permissions for MySQL specifically. 



Keep database passwords outside the web area 

It's a good idea to separate passwords from the web pages that use them. With PHP's i ncl ude ( )/ 
i ncl ude_once ( ) and requireO/requi re_once ( ) functions, it's very easy to drop in text (such 
as database passwords) from another file at runtime. Remember that these included files do not have 
to be in a PHP or web server— enabled directory! Whenever possible, keep them somewhere outside 
your web area or the file hierarchy viewable to the public through the web server. A good example is 
a directory above or outside of your web document root or in a home directory. 

Taking the database variables out of PHP files is also good for other reasons. If you have many PHP 
scripts using the same database, they can all use the same password file. When you suspect the 
password has been compromised, or when you change the password on a regular schedule, you 
need only alter one script for all the files to be updated. 

The unavoidable downside of this technique is that the file must be readable by the user through 
which the web server runs, such as wwwuser, httpd, or Apache. This usually involves changing the 
ownership of the file with the database credentials to that of the Apache web server user, and, of 
course, making sure that the mode of the file doesn't allow it to be world-readable. 

If you have a set of database variables you use infrequently — a configuration script or the like — you 
can keep it in a non-Apache-readable directory and change the permissions only on the rare occa- 
sions necessary. We infrequently have to go to the trouble to delete postings from our sites' forums. So 
it's not that much more work (and much more secure) to keep this file in a non-Apache-user-owned 
directory, once in awhile change the permissions just long enough to delete the offending post, and 
then immediately change everything back. 

If for whatever reason, you decide to put your database username, password, hostname, and database 
name into a PHP script in plain text, this is what you can expect. If the web server is functioning 
normally, the database passwords should be as safe as any file on that server. But if the daemon goes 
down, there is some chance your raw PHP (including plain-text database variables) will be delivered in 
a human-readable form. You can reduce this risk by avoiding the use of the . html suffix for PHP files. 
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In some versions of PHP, if database connectivity went down and you hadn't specified silent mode, 
you would see something like the following: 

Warning: MySQL Connection Failed: Access denied for user: 
' someuser@l ocal host ' (Using password: NO) in 
/home /web /html /mysqltest.php3 
on line 2 

This constitutes a security breach, because it reveals your MySQL username and whether or not you use 
a password. From PHP4 forward, MySQL error messages are no longer displayed by default. Two func- 
tions, my s q 1 _e r r n o ( ) and my s q 1 _e r r o r ( ) , allow you to opt for error codes or text warnings — but 
now you have to deliberately choose to ask for the information. Because, in most cases, you can opt for 
the more configurable d i e ( ) instead or remove error messages after debugging, it's still not a good idea 
to use my s q 1 _e r r o r on a public production server unless you scrupulously send messages to error logs 
using the error_l og ( ) function rather than to standard output. 

Learn to make backups 

And finally, the biggest part of database security may be backing up. Take an hour to learn the best 
way to back up data in your particular database (for example, via the mysql dump command in 
MySQL), and then schedule regular backups right away. Even better, with a little foresight you can 
also set up an automatic database backup schedule. 



Summary 

SQL is not rocket science. The four basic data-manipulation statements supported by essentially 
all SQL databases are SELECT, INSERT, UPDATE, and DELETE. SELECT gets data out of the data- 
base, INSERT puts in a new entry, UPDATE edits pieces of the entry in place, and DELETE gets rid 
of an entry. 

Designing databases is where most of the difficulty lies. Not all web developers will be asked to do 
this. The designer must think long and hard about the best way to represent each piece of data and 
relationship for the intended use. Well-designed databases are a pleasure to program with, while 
poorly designed ones can leave you pulling your hair out while contemplating numerous connec- 
tions and icky joins. 

SQL databases are created by so-called data structure statements. The most important of these are 
CREATE, ALTER, and DROP. As one would expect, CREATE TABLE defines a new table within a data- 
base. ALTER changes the structure of a table. DROP is the nuclear bomb of SQL commands because it 
deletes entire tables or sometimes even whole databases. 
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MySQL is one of the easiest databases to administer on all plat- 
forms, and because it's so lightweight, it can run on even 
low-powered PCs. Thus, PHP developers have long found it 
convenient to throw a copy of MySQL on client machines — even on lap- 
tops — for a complete local web development environment. Many devel- 
opers learn to run their own MySQL installations so that they can work at 
home or on the road, using the OS of their choice. Work teams also some- 
times prefer developers to each use a separate local MySQL installation, so 
that there is no single point of failure that could affect an entire develop- 
ment group. And many PHP-based open source projects assume complete 
familiarity with MySQL database administration for all developers. 

Unlike some other databases, it should be well within the capability of any 
PHP developer to self-administer a MySQL database. There is a plethora of 
tools, both in MySQL itself and available from third parties, to make this 
job even easier. Many PHP-based application packages, both commercial 
and open source, also require familiarity with a MySQL database to install, 
run, and debug the web app. So even if you don't plan to write all your PHP 
code yourself, getting comfortable with MySQL administration will pay 
many dividends. 



IN THIS CHAPTER 



Administering MySQL 
Backups 
Replication 
Recovery 
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Basic MySQL Client Commands 



It may surprise you to know that the binary named my s q 1 in your my s q 1 /bin directory is not the 
server, but the client (the server is mysql d). When you type mysql into a shell, you are using the 
MySQL command-line client to access some MySQL server. 

To connect to the MySQL server using the command-line client, the basic command is: 
mysql [-h hostname] [-P portnumber] -u username -p 

You almost certainly need to pass the username; if you don't, the client will try the name of your 
shell user. If you don't pass the password flag, mysql will check whether a password is needed for 
the user you claim to be — and if so, it will reject you. If you're connecting to a local host, you don't 
need the hostname flag; if you're connecting to the default port (3306), you don't need the port num- 
ber flag. There are a bunch of other options, but usually this is all you need the first time. Assuming 
that you use the username root, you will be prompted for the root password that you just set in the 
previous step. 

At this point, you will need to select a database to use. The command for that is: 
USE databasename ; 

The semicolon is optional for this command, but you need one for every other SQL command, so 
you might as well get used to using it. Until you create new databases, there are only two databases 
in a fresh install: mysql and test. If you just connected to MySQL as the root user, you have access 
to both; if you are connected as any other user, you have access only to test. 

The command SHOW TABLES; will dump a list of all the tables in this database. 

To quickly see the structure of a database table, use SHOW COLUMNS FROM tablename;. This dis- 
plays all the columns with their types, sizes, default values, and other helpful information. 

To see all the values in a table, just do a SELECT with unrestrictive conditions: 

SELECT * FROM tablename; 

Be careful though, since in live databases this kind of query can be huge and take up a lot of 
resources. If you have reason to suspect that the data set is more than a few rows, you should take 
steps to limit the query. 



SQL statements in your PHP code is to try them out (with suitable fake data plugged into the variables) 
using the MySQL command-line client rather than the PHP client. See Chapter 19 for more information 
on debugging SQL in your PHP. 

Finally, to get out of the MySQL client session, use the command quit;. Again, the semicolon is 
optional for this command. This should drop you back into your normal shell. 




See Chapter 13 for more information on how to write SQL statements such as SELECT, 
I NSERT, and so forth. Remember that one of the best ways of debugging problems with 
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MySQL User Administration 

A big part of using MySQL safely and effectively is understanding its privilege system and learning 
how to use the tools provided for controlling user privileges. 

MySQL allows you to grant quite fine-grained permissions to different users from different client 
locations. There are four descending levels of privileges: global, database, table, and column. So in 
theory, you could allow a particular user to write data only to certain columns of certain tables of 
certain databases on your MySQL server. Or you could just as easily give any database user con- 
necting from anywhere the same powers as the root database user (although this is totally not 
recommended). 

Of course, for security reasons it's generally a good rule of thumb to grant each user only the mini- 
mal permissions necessary to perform his or her function. 

There are two different ways to add or edit user permissions in MySQL (assuming that you're the 
root database user): by direct SQL statements (for example, putting a Y by hand into every relevant 
field of every relevant grant table) or by use of the GRANT and REVOKE syntax. The latter is easier, 
and less dangerous if you make a small mistake, since in most cases your query will choke with a 
SQL error instead of just leaving a gaping security hole. 

To add a new MySQL user, type the following: 

GRANT priv_type [(columnl, column2, column3)] 
ON database . [table] 

TO user@host IDENTIFIED BY ' new_password ' ; 

where columns and tables are optional and additional pri v_types can be appended in a comma- 
separated list. 

The types of privileges and their scope are shown in Table 14-1. 

Obviously, there's no point in trying to give anyone the SHUTDOWN privilege at the table level. You 
will merely get an error message referring you to the manual. If you grant A L L to a column, table, or 
database, the user will get only the basket of privileges appropriate to that level. 

You should be especially careful about giving users the following privileges, which are all dangerous: 
GRANT, ALTER, CREATE, DROP, FILE, SHUTDOWN, PROCESS. No normal database user, especially a 
PHP user, should need these permissions in production. 

The syntax for revoking privileges is very similar, although simpler: 

REVOKE priv_type [(columnl, column2, column3)] 
ON database[ .table] 
FROM userOhost; 
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TABLE 14-1 



MySQL Privilege Scope for Selected Privileges 



Privilege 


Global 


Database 


Table 


Column 


ALL 


✓ 








ALTER 


/ 




✓ 




C REATE 


/ 
✓ 


✓ 


✓ 




C REATE 

TEMPORARY 

TABLE 


/ 
✓ 


/ 
✓ 






n F I FTF 
U t L t I L 


✓ 


✓ 


✓ 




n d n d 

UKUr 




✓ 


✓ 




F Y FT I IT F 
t A t L U I L 




✓ 






F T I F 
r 1 Lt 




✓ 






INDEX 


/ 


/ 


/ 




INSERT 


/ 


/ 


/ 


/ 


i nr V TADI FQ 
LULK 1 Ad L to 


/ 


/ 






r KUL too 


/ 


/ 






DFFFDFMTFQ 

KtrtKtNLto 


/ 


/ 






nri n A n 
K t LUAU 


/ 


/ 






DFDI T P A T T f"l M 

K t r L 1 L A ! 1UN 

CLIENT 


/ 








REPLICATION 
S LAV E 


/ 








SELECT 


/ 


/ 


/ 


/ 


SHOW DATABASES 


/ 








SHUTDOWN 


/ 








SUPER 


/ 


/ 






UPDATE 


/ 


/ 


/ 


/ 


USAGE 


/ 


/ 






GRANT OPTION 


/ 


/ 


/ 
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After you grant or revoke privileges to any user, you need to force the database to reload the new 
privilege data into memory. You do this by issuing the FLUSH PRIVILEGES command . You could 
also start and stop the server, but that's impractical in many circumstances. 

This is all well and good, but by now you're probably thinking: But what actual permissions should I 
actually grant to my actual PHP user? Let's look at some common cases from the real world. 

Local development 

For purely local stuff, especially on a machine that isn't connected to the Internet all the time or is 
tucked securely behind a good firewall, almost anything goes. If you need to experiment with your 
schema, this is the place to do it — so it's appropriate to have permissions like ALTER, C RE ATE, 
DELETE, and DROP in addition to the normal SELECT, INSERT, UPDATE. A lot of people will find it 
convenient to just grant ALL PRIVILEGES on a certain database to a local user, like this: 

GRANT ALL PRIVILEGES on database.* 
TO username@l ocal host 
IDENTIFIED BY 'password' ; 

Standalone web site 

A self-hosted database probably needs to accept connections from numerous web servers in the same 
domain. In production, all machines should be limited to SELECT, INSERT, UPDATE, and possibly 
DELETE — although many systems never actually delete data, and it's a little safer not to do so. Since 
there probably won't be multiple databases on a standalone web site's production database, global 
permissions are faster with not much more real security risk. So a possible grant statement is: 

GRANT SELECT, INSERT, UPDATE ON *.* 
TO phpdbuser@% . exampl e . com 
IDENTIFIED BY 'password' ; 

However, this is the situation that is most likely to use master-slave replication. Often, these MySQL 
clusters are configured so that all writes go to the master, while the slaves do nothing but serve up 
very fast reads. In that case, you would give only SELECT privileges on each slave and only I NSERT 
and UPDATE privileges on the master — possibly to two different database users. 

Shared-hosting web site 

If you are an Internet service provider (ISP) that offers shared hosting, or a customer hosting your 
web site with one, your primary concern should be security over performance. Under no circum- 
stances do you want one user to be able to tamper with or delete data belonging to another user. 

Unless each user has her own MySQL instance running on her own port, the ISP administrator 
should not allow users to create or drop globally. Obviously, though, there is no good way to deny 
table creates or drops, which implies that each user will also be able to drop his own database if he 
so desires. Yes, that's right: If your users can define new tables, as they almost certainly will have to 
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in this situation, there's no good way to prevent them from blowing away all their data with a single 
command! That's part of the easy come, easy go thrill of MySQL. The database administrator can 
and should, however, prevent users from being able to do this to other users on the same server. 



Backups 

Database backups can be made in two ways: by copying the data directory directly (either manually 
or by means of the mysql hotcopy script on Unix) or by using the my sql dump tool to write out a 
SQL file that will replicate your database. The former is a little faster, but the latter is more flexible. 
With mysql dump you can choose to copy just the structure of the database, just the data, or both. 

The most basic usage of mysql dump is: 

mysqldump -u username -p databasename > dumpf i 1 ename . sql 
This command will dump a text file that can be read into another database server, like this: 

mysql -u root -p databasename < dumpf i 1 ename . sql 

Instead of directing the output of my s q 1 d ump to a file, you can also pipe it directly to another server, 
like this: 

mysqldump -u username -p databasename | 

mysql -h remote-host -u remoteuser -p -C databasename 

However, this can be less secure in some cases, since you have to tell the remote host to accept 
database-modifying connections from external clients. 

This basic command is fine as far as it goes — meaning that it will result in a nice SQL file contain- 
ing both the structure and data of the named database. But sometimes you will want something 
more specific than that: maybe just the structure or just the data or all the databases on that server 
or just some tables from your chosen database. MySQL allows you to both specify different combina- 
tions of databases and/or tables and to add option flags to your command. 

If you want to select specific tables to dump from your chosen database, just list them after the data- 
base name: 

mysqldump -u username -p databasename tablel table2 
> dumpf i 1 ename . sql 

If you want to dump some but not all databases on your server, use the - -databases flag and then 
list the databases. However, in this case, you will not be able to specify tables. 

mysqldump -u username -p --databases databasel database2 > 
dumpf i 1 ename .sql 
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If you want to dump all databases, use the - - a 1 1 - databases flag: 

mysqldump -u username -p - -al 1 -databases > dumpf i 1 ename . sql 

You can specify any of these options before specifying the databases and tables. There are many 
my sql dump options, but Table 14-2 lists the most commonly used options. 



TABLE 


mysqldump Options 


Ontinn 


Fvnlanation 


- - add - 1 ocks 


Adds table locking to SQL file for faster inserts on the target table. 
See also - - opt. 


--add-drop-tabl e 


Will overwrite each table definition. Be careful with this option, as 
you could delete data! If you don't use this option but a table of 
the same name already exists, you will get an error on the target 
database. 


-a, --all 


All options. Be careful! 


-c, - -compl ete- i nsert 


Use more complete insert statements with column names, instead 
of simply reading in values. 


h e 1 p 


r^icr"\la\/c riolr* mocc^oo \A/ith nntmnc 
L-MspidyD lltrip MICDSClge Willi UpilUllD. 


-1, --1 ock-tabl es 


Locks tables on the source machine before the dump. 


-n, - -no-create-db 


Will not create databases of the specified names if they don't exist 
already. Default with the - -databases and - -all - databases 
options. 


- 1, - -no-create- i nf o 


Will not create tables of the specified names if they don't exist 
already. 


-d, - -no-data 


Just the structure of the specified database(s) or tables. 


- -opt 


Equal to --qui ck --add-drop-table --add-locks -- 
extended-insert --lock-tables. Fastest possible dump. 
Make sure that you want to drop existing tables if there's a conflict. 


-q, --quick 


No buffering. 


-r, -- resul t-fi 1 e=fi 1 ename 


Dump result to file. In DOS, creates Unix-style line breaks. 


-w, - -where= ' condi ti on ' 


Select results by the WHERE clause in single quotes. 
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Because mysql dump is so easy to use, you should have no excuse for not adhering to a regular 
backup schedule. This is why cronjobs were invented! If your data changes relatively infrequently, 
you might be able to get away with weekly or fortnightly backups; if you have a fairly high-traffic 
site, you'll want to schedule one every night. 

Users of PHPMyAdmin have access to mysql dump through the Export tab. However, PHPMyAdmin 
currently offers only the most common options for your data dump. If you need more control over 
the format of your SQL file, you'll have to use mysql dump as previously described instead. 



Replication 

MySQL replication is based on a one-way single-master, single-or-multiple-slave model. The mas- 
ter database will handle all writes — meaning all I N S E RTs, UPDATES, and DELETES, as well as all 
schema changes. The slaves will periodically get these changes from the master and in the meantime 
will be available for highly optimized read-only data serving (meaning all SELECTs). The master 
does not know anything about slave databases. It simply makes its binary logs available, and the 
slaves do all the rest: scheduling updates, connecting to the master, getting the changes, applying 
the changes, and so on. Thus, slaves are aware of the identity of the master, but masters are not 
aware of the identities of slaves. 

If the master database goes down for any reason, no replacement will be automatically elected. The 
entire system is likely to become unresponsive, as the slaves spend many resources trying in vain to 
connect to the master for updates, while PHP tries to perform writes without success. The database 
administrator will have to manually break the existing master-slave relationships and designate a 
new master by hand. Luckily, if something goes wrong with the master, there's no way the slaves 
will have gotten out of sync — so if a database administrator notices the problem and is available to 
deal with it, changing to a new master database should be relatively quick. 

Because there have been many changes and upgrades to the replication function in recent versions 
of MySQL, many recent versions are incompatible with other recent versions in a replication setup. 
If you want to try replication, we recommend that you make sure all the database servers involved 
are using the same version of MySQL, and furthermore, that this version is 4.0. 3+. If you are trying 
to replicate with disparate versions of MySQL between 3.23 and 4.0.3, it is very likely that things 
will not work properly. 

In a nutshell, the operations that must be performed to establish MySQL replication are: 

1 . Grant permissions to slave user on master. 

2. Take snapshot of master data; copy to slave machines. 

3. Shut down MySQL servers. 

4. Restart MySQL servers with correct server - ids. 

5. Establish master-slave relationship from each slave. 
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Now we'll explain the process in more detail. 

You will need to create an account on the master database for slaves to use, with the REPLICATE 
S LAV E privilege. You do not need to grant any other privileges to this account. 

GRANT REPLICATE SLAVE ON *.* 

TO replicant®' 0 /' IDENTIFIED BY 'replpwd'; 

Next, lock the master server and take a snapshot of its state immediately before the replication. On 
the master server, log in to a MySQL client session as the root user and issue the commands: 

FLUSH TABLES WITH READ LOCK; 
SHOW MASTER STATUS; 

This will prevent any changes from being made to the database until you are ready to bring up the 
cluster. You may also (depending on whether this server has been run with binary logging) see some 
data about the location of the binary log file and offset. If so, write it down; if not, use the default 
values ' ' (empty string) and 4, respectively. 

Next, copy the master database structure and data. There are two ways to do this. The first is to 
simply copy the mysql/data directory into a tarball or zip file by using one of these commands or a 
GUI procedure: 

tar -cvf master_snapshot . ta r data/ 
zip master_snapshot.zip data/ 

Alternatively, you can use mysql dump to make a backup as described in the next section. Copy this 
snapshot file to each slave server. 

Now shut down all the master and slave servers. Quit any mysql client shell sessions, and issue the 
command: 

mysqladmin -u root -p shutdown 

on each server. The reason you are shutting the servers down is to give them unique server - id 
values. They will use these values to find each other when they establish the master-slave relation- 
ship. This value is set in each server's my . cnf file and will be read in on startup. On Windows, the 
my . cnf file is located in one of two places: C : \my . cnf or C : \ [Wi ndows di rectory ] \my . ini. 
On Unix systems, the global my . cnf file is found in / etc/ my. cnf and the server-specific file 
(which is probably the one you want to use) is found in / path /to/ mysql / data / my. cnf. 

First, set the server-id on the master machine. Find or create a file called my . c n f in the proper 
location for your platform, and make sure that it contains the lines: 

[mysql d] 
1 o g - b i n 
server-i d = l 
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Restart the master server: 

bi n/mysql d_saf e --user=mysql 

In each slave server's my . cnf files, you need only the server- i d, not the 1 og-bi r line. The 
most important thing is that you are absolutely positive that all the server - id values in your 
cluster are unique! If they are not, bad things will happen. So the first slave's my . cnf file would 
contain this line: 

[mysql d] 
server-id=2 

The second slave would set server - i d=3, and so forth. 

Now, before you bring up each slave server, you may need to do a little bit of housekeeping. If this 
MySQL server has been used as a slave before, you may want to delete the files data /master, info 
and data/relay-log. info. You may also want to delete the .err and . pi d files in the data 
directory. Also, if you copied the master's data snapshot into a tarball or zip file, now is the time to 
copy it to the slave with a command like one of these (from the mysql directory): 

tar -xvf master_snapshot . ta r 
unzip master_snapshot.zip 

If you used mysql dump instead, you have to wait until the server is back up. 

Now bring up the slave: 

bi n/mysql d_safe --user=mysql --skip-slave-start --log-warnings 

If you took your master data snapshot with mysql dump, now is the time to apply the SQL file to 
the slave: 

mysql -u root -p databasename < master_snapshot . sql 

Finally, you will establish the master-slave relationship. Log in to a mysql shell and then enter the 
following commands, substituting the values you wrote down at the beginning of the process: 

CHANGE MASTER TO 

MASTER_HOST= ' masterhostname ' , 

MASTER_USER= ' repl icant' , 

MASTER„PASSWORD='replpwd' , 

MASTER_LOG„FI LE= ' 1 , 

MASTER_L0G_P0S=4; 
START SLAVE; 

If there are problems, they will appear in the slave machine's error log. 



216 



Recovery 

Normally, MySQL does not require much attention. MySQL servers have happily puttered away for 
months if not years with minimal administration. However, bad things do happen to data: Hard 
disks melt down, hosting centers lose power suddenly, and human error is a constant and awful 
probability. If you have insufficient memory for all the applications you're running on a server, or 
insufficient disk space on a partition, you may also get an error that requires a recovery process. 
It must be admitted that MySQL seems to have minor database corruption events with greater fre- 
quency than heavier-weight databases — or perhaps it's just easier for the administrator to notice 
these events. 

Luckily, MySQL is designed to make it amazingly easy to repair small flaws in your data and get 
back up quickly. Only once have we had to actually scrap an entire database after repeated attempts 
at recovery, and that disaster was caused by a total hard disk failure, which is something a developer 
can do nothing to plan for or recover gracefully from — except make frequent backups. 

MySQL has long shipped with a command-line tool called my i samch k for checking and repairing 
tables. This was a fine script but it suffered from one flaw: It could be run effectively only when the 
database was shut down. That's fine when you're actually recovering from a disaster, since you're 
unlikely to be able to start your database anyway, but it's a significant barrier to trying to head off 
problems by regularly checking your data tables. Luckily, there is now a new tool that can be used 
during operation — my sql check. You can continue to use myi samch k (used only for myi sam 
tables) when the server is not running. Refer to the MySQL manual for more information on trouble- 
shooting table problems. 

Both these tools basically can do three things: check a MylSAM table for errors, repair problems, and 
optimize the database. The syntax by which you use the scripts is different, however. 

myisamchk 

The my i samch k utility is invoked like this: 
myisamchk [options] table_name 

or 

myisamchk [options] /path/ to/my sql /data/database/ tab! e . MY I 

You can wildcard both database directories and table names with an asterisk, which is more com- 
mon than specifying a table, since you usually don't know exactly which table is causing the prob- 
lems. Use the following commands to check all the tables of all the databases on a server: 

myisamchk [options] /path/to/mysql /data/*/* . MY I 
myisamchk [options] /path/to/mysql /data/*/* . MYD 

.MYI extensions designate index files, and .MYD extensions designate data files — you need to 
check both. 
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With no option flags, myi samchk will simply check the designated table. If you pass the - r option 
flag, myi samchk will repair the designated tables. You can also check and repair any corrupted 
tables in a single operation: 

myisamchk --silent --force --fast --update-state -0 
key_buf f er=64M -0 sort_buf f er=64M -0 read_buf f er=l -0 
write_buffer=lM /path/to/mysql /data/*/* . MYI 

The command myisamchk - r tablename will also optimize a table that has been fragmented by 
deletes and updates. 

mysqlcheck 

The my s q 1 c h e c k tool has several handy advantages over myisamchk. As previously mentioned, 
it can be used while the server is running — even while serving up queries. It works on databases 
rather than tables, using the same syntax as the mysql dump tool. And instead of having to remem- 
ber the meaning of a bunch of option flags, you can copy and rename the executable to get different 
behaviors. 

The my s q 1 c h e c k tool is invoked in one of these ways: 

mysqlcheck [options] databasename tablel table2 table3 
mysqlcheck [options] --databases databasel database2 
mysqlcheck [options] - -al 1 -databases 

To repair, analyze, or optimize databases, you simply copy the mysql check file and change its 
name tomysqlrepair,mysqlanalyze,ormysqloptimize — and then invoke it the same way. 
So, for instance, to repair all the databases on your server, you might give this command: 

mysqlrepair -u root -p - -al 1 -databases 

MySQL AB recommends that you set up a regular schedule of data file checking via cronjob, plus 
run one of these utilities every time you start up your MySQL server. This should help keep your 
data compact for fast reads, head off problems while they're still tiny, and minimize your chances of 
a database problem that is visible to your users. 



Summary 

MySQL is one of the easiest databases to administer, and learning to do so provides many benefits 
to PHP developers. MySQL installations have become easier of late on many platforms, and there are 
GUI as well as command-line tools available to help you view the structure of your database, man- 
age database users, and make backups. More advanced MySQL administration tasks include disaster 
recovery and replication — both of which are probably as easy to accomplish on MySQL as they 
could possibly be made. However, even long-time MySQL users should consider the impact of recent 
changes to the MySQL-PHP relationship: licensing issues, client-version incompatibility, the new 
mysql extension, and transactions. 
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After you've installed and set up your MySQL database, you can 
begin to write PHP scripts that interact with it. Here, we will try 
to explain all the basic functions that enable you to pass data back 
and forth from web site to database. 



Information related to creating a MySQL database is at the end 
of this chapter, because it is a more advanced skill that builds 
on the fundamental MySQL skills discussed in the earlier parts of the chapter. 



Connecting to MySQL 

The basic command to initiate a MySQL connection is 

mysql_connect( Ihostname , $user, $password); 

if you're using variables, or 

mysql _connect ( ' 1 ocal host ' , 'root', 'sesame'); 

if you're using literal strings. 

The password is optional, depending on whether this particular database 
user requires one (it's a good idea). If not, just leave that variable off. You can 
also specify a port and socket for the server ($hostname : port : socket), 
but unless you've specifically chosen a nonstandard port and socket, there's 
little to gain by doing so. 

The corresponding my s q 1 i function is mysql i_connect, which adds a 
fourth parameter allowing you to select a database in the same function you 
use to connect. The function mysql i_sel ect_db exists, but you'll need it 
only if you want to use multiple databases on the same connection. 
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You do not need to establish a new connection each time you want to query the database in the same 
script. You will need to run this function again, however, for each script that interacts with the data- 
base in some fashion. 



Next, you'll want to choose a database to work on: 
mysql_select_db($database) ; 

if you're using variables, or 

mysql _sel ect_db ( ' phpbook ' ) ; 



if you're using a literal string. 

You will sometimes see these two functions used with an @ prepended, such as ©mysql „ 
sel ect„db ( $database). This symbol denotes silent mode, meaning the function will 
not return any message on failure, as a security precaution. You should have di spl ay_errors set to 
off on production servers anyway. 

You must select a database each time you make a connection, which means at least once per page or 
every time you change databases. Otherwise, you'll get a Database not selected error. Even if you've 
created only one database per daemon, you must do this, because MySQL also comes with default 
databases (called mysql and test) you might not be taking into account. 

You may find it convenient to group all your connection information into a custom connect func- 
tion and put it someplace where you can access it from all your scripts, such as the php includes 
directory, or in the case of a virtual server, a site-specific include file. This function might look like 
the following: 

// Connect to a single db 
f uncti on qdbconn ( ) ( 

SdbUser = "myuser" ; 

SdbPass = "mypassword" ; 

SdbName = "mydatabase" ; 

SdbHost = "my host " ; 

if ( ! ( $1 i n k=mysql_connect ( SdbHost , SdbUser, SdbPass))) { 
error_l og(mysql_error( ) , 3, " /tmp/phpl og . err " ) ; 

1 

if ( !mysql_sel ect_db( SdbName , $link)) { 

error_l og(mysql_error( ) , 3, " /tmp/phpl og . err ") ; 



If you like, you could extend this function by creating links (for example, $ 1 i n k 1 , $ 1 i n k 2) to 
multiple databases on the same server. This code also records a MySQL error message in the PHP 
error log. 

Now that you've established a connection to a specific database, you're ready to make a query. 
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Making MySQL Queries 

A database query from PHP is basically a MySQL command wrapped up in a tiny PHP function 
called my sql _query ( ) . This is where you use the basic SQL workhorses of SELECT, I NSERT, 
UPDATE, and DELETE that we discussed in Chapter 13. The MySQL commands to CREATE or DROP 
a table can also be used with this PHP function if you do not wish to make your databases using the 
MySQL client. 

You could write a query in the simplest possible way, as follows: 

mysql_query( "SELECT Surname FROM personal_i nf o WHERE ID < 10"); 

PHP would dutifully try to execute it. However, there are very good reasons to split up this and 
similar commands into two lines with extra variables, like this: 

$query = "SELECT Surname FROM personal_i nf o WHERE ID < 10"; 
$result = my sql _query ( $query ) ; 

The main rationale is that the extra variable gives you a handle on an extremely valuable piece of 
information. Every MySQL query gives you a receipt whether you succeed or not — sort of like a 
cash machine when you try to withdraw money. If things go well, you hardly need or notice the 
receipt — you can throw it away without a qualm. But if a problem occurs, the receipt will give you 
a clue as to what might have gone wrong, similar to the "Is the machine not dispensing or is your 
account overdrawn?" type of message that might be printed on your ATM receipt. 

Another advantage of assigning the query string to a variable is that you can more easily view the 
query if you run into an error. Of course, you would accomplish this by writing the variable out to 
an error log — never by dumping it out to the browser in production! 

The function my s q 1 _q u e ry takes as arguments the query string (which should not have a semicolon 
within the double quotation marks) and optionally a link identifier. Unless you have multiple con- 
nections, you don't need the link identifier. It returns a TRU E (nonzero) integer value if the query 
was executed successfully even if no rows were affected. It returns a FALSE integer if the query was 
illegal or not properly executed for some other reason. 

For purposes of this chapter, we've left the link identifier off; however, if you need to use multiple 
databases in your script, you can use code like this: 

$query = "SELECT Surname FROM personal_info WHERE ID < 10"; 
$result = mysql_query ( $query , $link_l); 
$query = "SELECT * FROM orders WHERE date > 20030702"; 
$result = mysql_query($query, $link_2); 

As expected, the MySQL improved analog for this function is my sql i_query. It is very similar to its 
counterpart; however, the link and query parameters change places, and a third parameter allows 
you to specify a result flag indicating how PHP should handle the result. 
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If your query was an INSERT, UPDATE, DELETE, CREATE TABLE, or DROP TABLE and returned TRUE, 
you can now use my sql _af f ected_rows to see how many rows were changed by the query. This 
function optionally takes a link identifier, which is only necessary if you are using multiple con- 
nections. It does not take the result handle as an argument! You call the function like this, without a 
result handle: 

$af f ected_rows = mysql_affected_rows( ) ; 

If your query was a SELECT statement, you can use my sql _num_rows ( $ resul t ) to find out how 
many rows were returned by a successful SELECT. 

The mysql i__af f ected_rows and mysql i_num_rows behave exactly the same as their mysql_ 
counterparts. 




The mysql _num_rows function can be useful in paginating large data sets returned by 
MySQL queries. 



Fetching Data Sets 

One thing that often seems to temporarily stymie new PHP users is the whole concept of fetching 
data from PHP. It would be logical to assume that the result of a query would be the desired data, 
but that is not correct. As we discussed in the previous section, the result of a PHP query is an inte- 
ger representing the success or failure or identity of the query. 

What actually happens is that amysql_query() command pulls the data out of the database and 
sends a receipt back to PHP reporting on the status of the operation. At this point, the data exists in 
a purgatory that is immediately accessible from neither MySQL nor PHP — you can think of it as a 
staging area of sorts. The data is there, but it's waiting for the commanding officer to give the order 
to deploy. It requires one of the mysql_fetch functions to make the data fully available to PHP. 

The fetching functions are as follows: 

■ mysql _fetch_row: Returns row as an enumerated array 

■ mysql_fetch_object: Returns row as an object 

■ mysql _fetch_ar ray: Returns row as an associative array 

■ mysql_resul t: Returns one cell of data 



, ' ' - - f " ,n our nul11 ble opinion, the functions mysql _fetch_fi el d and mysql _f etc h_ 
r " w 1 engths are misleadingly named. They both provide information about database 

entries rather than the entry values themselves. For instance, one might expect a function named 
mysql_f etch_f i el d to be a quick way to fetch a single-field result set (the ID associated with a par- 
ticular username, for instance), but that is not the case at all. The actual purpose of these functions is 
explained in Table 15-2 at the end of the chapter — but for the moment, the point is not to be misled 
into thinking that these functions will return database values. 
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The differences among the three main fetching functions is small. The most general one is mysql _ 
f etch_row, which can be used something like this: 

$query = "SELECT ID, LastName, FirstName 

FROM users WHERE Status = 1" ; 
$result = my sql _query ( $query ) ; 
while ($name_row = mysql _f etch_row( $ resul t ) ) { 

pri nt( " ( $name_row[0] } ( $name_row[l] ) ( $name_row[2] )<BR>\n" ) ; 

1 

This code will output the specified rows from the database, each line containing one row or the 
information associated with a unique ID (if any). 

'- - "o'V'b" m an enumerated array, the integers in brackets are called field offsets. Remember that 

they always begin with the integer zero. If you start counting at 1, you will miss the value 
of your first column. 

The function my sql _f etch_ob ject performs much the same task, except the row is returned as an 
object rather than an array. Obviously, this is helpful for those among the PHP brethren who utilize 
the object-oriented notation: 

$query = "SELECT ID, LastName, FirstName 

FROM users WHERE Status = 1" ; 
$result = my sql _query ( $query ) ; 
while ($row = my sql _f etch_ob j ect ( $ resul t ) ) { 

echo "($row->ID), ( $row->LastName ) , ( $row->Fi rstName}<BR>\n" ; 

) 

The most useful fetching function, mysql_f etch_a rr ay, offers the choice of results as an associa- 
tive or an enumerated array — or both, which is the default. This means you can refer to outputs by 
database field name rather than number: 

$query = "SELECT ID, LastName, FirstName 

FROM users WHERE Status = 1" ; 
$result = my sql _query ( $query ) ; 
while ($row = mysql_fetch_array($resul t) ) { 

echo " ( $row[ ' ID ' ] } , 1 $row[ ' LastName ']) , { $ row[ ' Fi rs tName ' ] )<BR>\r " ; 

1 

Remember that mysql_fetch_array can also be used exactly the same way as mysql„fetch_ 
row — with numerical identifiers rather than field names. By using this function, you leave your- 
self the option. If you want to specify offset or field name rather than making both available, you 
can do it like this: 

$offset_row = my sql _f etch_a rray ( $resul t , MYSQL_NUM) ; 
or 

$associ ati ve_row = mysql_fetch„array ( $resul t , MYSQL_ASSOC ) ; 
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It's also possible to use MYSQL_BOTH as the second value, but because that's the default, it's 
redundant. 

In early versions of PHP, mysql„f etch_row was considered to be significantly faster than mysql_ 
fetch_object and mysql_fetch_array, but this is no longer an issue, as the speed differences 
have become imperceptible. The PHP junta now recommends use of my sql _f etch_a r ray over 
mysql_f etch_row because it offers increased functionality and choice at little cost in terms of pro- 
gramming difficulty, performance loss, or maintainability. 

Last and least of the fetching functions ismysql_result(). You should only even consider using 
this function in situations where you are positive you need only one piece of data to be returned 
from MySQL. An example of its usage is: 

Squery = "SELECT count(*) FROM personal_i nfo" ; 
$db_result = mysql _query ( $query ) ; 
$datapoint = mysql_resul t( $db„resul t , 0, 0); 

The mysql_result function takes three arguments: result identifier, row identifier, and (option- 
ally) field. Field can take the value of the field offset as above or its name as in an associative array 
("Surname") or its MySQL field- dot-table name ("personal _i nfo . Surname"). Use the offset if at 
all possible, as it is substantially faster than the other two. Even better, don't use this function with 
any frequency. A well-formed query will almost always return a specific result more efficiently. 

~-T7v ' I . ' You should never use m y s q 1 r e s u 1 1 ( ) to return information that is available to you 

through a predefined PHP-MySQL function. The classic no-no is inserting a row and 
then selecting out its ID number (extra demerits if you select on MAX ( I D ) !). Wicked bad style — use 

mysql _i nsert_i d ( ) instead. 

All of the PHP functions for fetching MySQL data have identical mysql i counterparts. They take the 
same parameters and return comparable results. 

A special MySQL function can be used with any of the fetching functions to more specifically 
designate the row number desired. This is mysql_data_seek, which takes as arguments the 
result identifier and a row number and moves the internal row pointer to that row of the data set. 
The most common use of this function is to reiterate through a result set from the beginning by 
resetting the row number to zero, similar to an array reset. This obviates another expensive data- 
base call to get data you already have sitting around on the PHP side. Here's an example of using 
mysql_data_seek( ): 

<?php 

echo( "<TABLE>\n<TRXTH>Titles</THX/TR>\n<TR>") ; 
$query = "SELECT title, publisher FROM books"; 
$result = mysql_query ( $query ) ; 

while ($book_row = my sql_f etch_a r ray ( $ resul t ) ) ( 
echo( "<TD>$book_row[0]</TD>\n" ) ; 

} 

echo("</TRX/TABLEXBR>\n" ) ; 

echo( "<TABLE>\n<TRXTH>Publ i shers</THX/TR>\n<TR>" ) ; 
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mysql_data_seek( $resul t , 0); 

while ($book_row = mysql _f etch_a rray ( $resul t) ) ( 
echo( "<TD>{$book_row[l] )</TD>\n" ) ; 

) 

echo( "</TRX/TABLEXBR>\n" ) ; 
?> 

Without using mysql_data_seek, the second usage of the result set would turn back no 0 rows 
because it has already iterated through to the end of the dataset and the pointer stays there until 
you explicitly move it. This handy function helps greatly when you are formatting data in a way that 
does not place fields in columns and records in rows. 



Getting Data about Data 

You only need four PHP functions to put data into or get data out of a preexisting MySQL database: 
mysql_connect, mysql _s el ect_db, mysql _query, and mysql_fetch_array. Most of the rest 
of the functions in this section are about getting information about the data you put into or took out 
of the database or about the construction of the database itself. PHP offers extensive built-in func- 
tions to help you learn the name of the table in which your data resides, the data type handled by 
a particular column, or the number of the row into which you have just inserted data. With these 
functions, you can effectively work with a database about which you know very little. 

The MySQL metadata functions fall into two major categories: 

■ Functions that return information about the previous operation only 

■ Functions that return information about the database structure in general 

A very commonly used example of the first type is my s q 1 _i n s e r t_i d ( ) , which returns the auto- 
incremented ID assigned to a row of data you just inserted. A commonly used example of the second 
type is mysql _f i el d_type ( ) , which reveals whether a particular database field's data must be an 
integer, a varchar, text, or what have you. Observe however, that this function is also deceptively 
named. Rather than returning the MySQL type, it returns the PHP data type. For example, an 
ENUM-type field will return 'string'. Use my s q 1 _f i e 1 d_f 1 a g s to return more specialized field 
information. This should be apparent when you consider that it works on a result rather than on an 
actual MySQL field. It would be useful to have a function that got the possible values for an ENUM 
field, but there isn't a canned version at this point. Instead, use a "describe table" query and parse 
the result using PHP's regex functions. 

Most of the data-about-data functions are pretty self-explanatory. There are a couple of things to 
keep in mind when using them, though. First, most of these functions are only effective if used in 
the proper combination — don't try to use a mysql_af f ected_rows after a SELECT query and then 
wonder what went wrong. Second, be careful about security with the functions that return informa- 
tion about your database structure. Knowing the name and structure of each table is very valuable 
to a cracker. And finally, be aware that some of these functions are shopping baskets full of simpler 
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functions. If you need several pieces of information about a particular result set or database, it could 
be faster to use mysql_f etch_f i el d than all the my sql _f i el d functions one after the other. 

All of the MySQL metadata functions are fairly easy to use. However, their efficacy is directly related 
to intelligent database design rather than a mere marker of the PHP's strengths. Good database 
practices will make these functions useful over the long haul. The my sql i equivalent functions are 
perfect analogues in each of these cases. 



Multiple Connections 



Unless you have a specific reason to require multiple connections, you only need to make one data- 
base connection per PHP page. Even if you escape into HTML many times within the page, your 
connection is still good (assuming that it was good in the first place). You do not want to make mul- 
tiple connections if you don't have to, because that is one of the most costly and time-consuming 
parts of most database queries. 

Conversely, there's no easy way to keep your connection open from page to page — because PHP 
and MySQL would never know for sure when to close it after visitors wander off. Therefore, your 
connection is closed at the end of each script unless you use persistent connections. 

The main time that you need to use different connections is when you're querying two or more com- 
pletely separate databases. The most common situation in which you might do this is when you're 
using MySQL in a replicated situation. MySQL replication is accomplished through a master-slave 
setup, where you typically get reads from a slave and make writes to the master. 

To use multiple connections, you simply open connections to each database as needed and make 
sure to hang on to the right result sets. PHP will help you do this by utilizing the result identifiers 
discussed in the "Making MySQL Queries" section earlier in the chapter. You pass the identifiers 
along with each MySQL function as an optional argument. If you're completing all your queries on 
one connection before moving on to the next, you don't even need to do this; PHP will automatically 
use the last link opened. 

In this example, we are using connections from three different databases on different servers: 
<?php 

$linkl = mysql _connect ( ' hostl ' , 'me', 'sesame'); 
mysql_select_db('userdb' , $linkl); 
$queryl = "SELECT ID FROM usertable 

WHERE username = ' $username ' " ; 
$resultl = mysql_query ( Squeryl , $linkl); 
$arrayl = mysql_fetch_array ( $resul tl ) ; 
Susercount = mysql _num_rows ($ resul tl ) ; 
mysql _cl ose( $1 i nkl ) ; 

$today = '2002-05-01' ; 

$ 1 i n k 2 = mysql _connect ( ' host2 ' , 'myself, 'benne'); 
mysql _s el ect_db ( 'inventorydb', $ 1 i n k 2 ) ; 
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$query2 = "SELECT sku FROM widgets 

WHERE ship_date = '$today'"; 
$result2 = mysql_query ( $query2 , $link2); 
$array2 = mysql_fetch_array ( $resul t2 ) ; 
$widgetcount = mysql _num_rows ( $ resul tZ ) ; 
my sql_cl ose ( $1 i n k2 ) ; 



if ($usercount > 0 && $widgetcount > 0) ( 

$ 1 i n k 3 = mysql „connect (' host3 ' , 'I', 'seed'); 
mysql _s el ect_db ( 'salesdb', $ 1 i n k 3 ) ; 

$query3 = "INSERT INTO saleslog (ID, date, userlD, sku) 

VALUES (NULL, 'Itoday', ' $arrayl [0] ' , '$array2[0] 
$result3 = mysql_query ( $query3 , $ 1 i n k 3 ) ; 
SinsertID = my sql_i nsert_i d ( $1 i n k3 ) ; 
mysql _cl ose ( $1 i n k 3 ) ; 
if (SinsertID >= 1) ( 
pri nt (" Perfect entry"); 

} 

else j 

pri nt (" Danger , danger, Will Robinson!"); 

} 

) else { 

print("Not enough information"); 

1 

?> 



In this example, we have deliberately kept the connections as discrete as possible for clarity's sake, 
even going to the trouble to close each link after we use it. Without the mysql _cl ose ( ) commands 
we would be running multiple concurrent connections — which you may want to do. There's noth- 
ing stopping you from doing so. Just remember to pass the link value carefully from one function to 
the next, and you should be fine. 



Building in Error Checking 

This section could have been titled "Die, die, die!" because the main error-checking function is actu- 
ally called d i e ( ) . There was something about that title that failed to reinforce the warm, hospitable 
learning environment we cherish, so we went with the more prosaic subheading. 

di e ( ) is not a MySQL-specific function — the PHP manual lists it in "Miscellaneous Functions." It 
simply terminates the script (or a delimited portion thereof) and returns a string of your choice. 

mysql_query( "SELECT * FROM mutual_funds 

WHERE code = ' Ssearchstri ng ' " ) 
or die( "Please check your query and try again."); 

Notice the syntax: the word o r (you could alternatively use | | , but that isn't as much fun as saying 
or die) and only one semicolon per pair of alternatives. 
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Until quite recently, MySQL via PHP returned very insecure and unenlightening (except to crackers) 
error messages upon encountering a problem with a database query, d i e ( ) was often used as a way 
to exert control over what the public would see on failure. Now that no error messages are returned 
at all, d i e ( ) may be even more necessary — unless you want your visitors to be left wondering 
what happened. 

Other built-in means of error-checking are error messages. These are particularly helpful during the 
development and debugging phase, and they can be easily commented out in the final edit before 
going live on a production server. As mentioned, MySQL error messages no longer appear by default. 
If you want them, you have to ask for them by using the functions my s q 1 _e r r n o ( ) (which returns 
a code number for each error type) ormysql_error() (which returns the text message). Then you 
can send them to a custom error log by using the e r r o r_l o g ( ) function: 

if ( !mysql_select_db($bad_db)) ( 
print(mysql_error( ) ) ; 

} 

There's more to database error handling than judicious use of d i e ( ) , however. Servers become 
unavailable, data sets get corrupted, and so forth. We've been fairly liberal in setting up connections 
and executing queries, but ideally, every interaction with the database should be nested inside a 
conditional that returns the desired result on success and a nice clean error page on failure. This is 
where d i e ( ) drops the ball. Execution immediately stops for the entire script, leaving off, if noth- 
ing else, closing tags for your HTML page if they are defined in PHP. Additionally, there may be 
plenty more perfectly good scripting or HTML left to go on the page — code that is unaffected by a 
dropped database connection or a failed query. Finally, d i e ( ) doesn't let you know anything went 
wrong. Do you really think that your users will tell you? Probably not. It's much more realistic that 
they will leave your site in disgust and never return. An example of good error checking is: 

function printError($errorMesg) { 

printf ( "<B>%s </BXBR>\n", SerrorMesg); 

1 

function noti fy ( SerrorMesg ) ( 

mai 1 (webmaster@exampl e . com , "An Error has occurred at 
example.com", lerrorMesg) 

} 

if ( $ 1 ink = mysql_connect("host", "user", "pass")) { 

// Things to do if the connection is successful 
} else { 

pri ntError( "Sorry for the inconvenience; but we are unable 
to process your request at this time. Please check back 
later"); 

noti fy ( " Probl em connecting to database in $SCRIPT_NAME at 
1 ine 12 on date( ' Y-m-D ' )"); 

} 

Even better, if you really want to get your feet wet with PHP6's new object-oriented programming 
(OOP) features, try using exceptions, which are covered in Chapter 30. 
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Creating MySQL Databases with PHP 

You can, if you wish, actually create your databases with PHP rather than using the MySQL client 
tool. This practice has potential advantages — you can use an attractive front end that may appeal to 
those who find the MySQL command-line client horribly plain or finicky to use — counterbalanced 
by one big disadvantage, which is security 

To create a database from PHP, the user of your scripts will need to have full CREATE /DROP privi- 
leges on MySQL. That means anyone who can get hold of your scripts can potentially blow away all 
your databases and their contents with the greatest of ease. This is not such a great idea from a secu- 
rity standpoint. 

If you're even considering creating databases with PHP, do yourself a big favor and at least don't store 
the database username and password in a text file. Make yourself type your database username and 
password into a form and pass the variables to the inserting handler each and every time you use 
this script. This is one case where keeping the variables in an include file outside your web tree is 
not sufficient precaution. Better yet, run the scripts manually from the command line through SSH: 

mysql -u <username> -p <databasename> < sql-script.sql 
For those times when you need to create databases programmatically, the relevant functions are: 

■ mysql_create_db(): Creates a database on the designated host, with name specified in 
arguments 

■ mysql _d r o p_d b ( ) : Deletes the specified database 

■ mysql__query(): Passes table definitions and drops in this function 



A bare -bones database-generation script might look like this: 
<?php 

SlinkID = my sql _connect ( ' 1 oca 1 host ' , 'root', 'sesame' 

my sql_crea te_db ( ' new_db ' , $1 i n kl D ) ; 

mysql_sel ect_db( ' new_db ' ) ; 

$query = "CREATE TABLE new_table ( 

id INT NOT NULL AUT0_I NCREMENT PRIMARY KEY, 
new_col VARCHAR( 25 ) 

)"; 

$result = my sql _query ( $query ) ; 
$axe = mysql_drop_db( ' new_db ' ) ; 

?> 



Several other GUI tools are available that are not database-specific but will probably work with 
MySQL. As MySQL has become more and more popular, a number of applications for both 
Windows and Linux have come into play that allow you to administer MySQL databases in the 
graphical fashion you may have become accustomed to. Like their web counterparts, these applica- 
tions offer full administrative control, but without the headache of exposing yourself to the security 



229 



Part II 



MySQL Database Integration 



risk of a web-based interface. The list changes often as software comes and goes, so a listing here 
would probably very quickly go out of date. However, the MySQL web site keeps a pretty compre- 
hensive list at http : //dev .mysql . com. 

MySQL data types 

The actual PHP functions used to create MySQL databases are trivial compared to the MySQL data 
structure statements that are passed in those functions. The "Database Design" section of Chapter 13 
has general rules on how to conceptualize a database schema and use the CREATE, DROP, and ALTER 
statements. To implement your abstract schema in MySQL, however, you also need to understand 
MySQL data types and how to use them. 

The general rule is to use the smallest and most specific data type that will adequately meet the 
needs of this particular column in your database. MySQL is known for having compact types, such 
as TINY I NT and TI NYTEXT, that are good for things like 0/1 values or first names. It also has very 
large types that can store 4GB (or more) of data in one field. 

There are three buckets of MySQL data types: numeric types, date and time types, and string (or 
character) types. For the most part, their use is fairly straightforward — in the sense that the aver- 
age user is not going to know or care whether you used an INT or a MED I UM I NT. However, if you're 
the type of programmer who cares about doing everything in the absolutely tightest and fastest way 
possible, the MySQL manual gives subtle tips on maximizing efficiency — for instance, always use 
the DECIMAL type with money, or it takes 8 bytes to store a DATETIME but only 4 bytes to store a 
Unix TIMESTAMP, which PHP can convert to any date-time format you desire. Careful perusal of the 
"Column Types" section of the MySQL manual (at www .mysql .com/ doc/en /Col umn_types . html ) 
may yield hidden treasures of insight. 

Table 15-1 shows the current MySQL data types and their possible values. M stands for the maxi- 
mum number of digits displayed, and D stands for the maximum number of decimal places in a 
floating-point number. Both are optional. 



TABLE 15-1 



MySQL Data Types 


Name and Aliases 


Storage size 


Usage 


TINYINT(M) 


BIT, BOOL, BOOLEAN are 
synonyms for T I NY I NT ( 1 ) 


1 byte 


If unsigned, stores values from 0 to 255; otherwise, 
from -128 to 127. A new Boolean type will appear 
in future, but until now has been implemented as a 

TINYINT(l). 


SMALLINT(M) 


2 bytes 


If unsigned, stores values from 0 to 65535; 
otherwise, from -32768 to 32767. 
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Name and Aliases 


Storage size 


Usage 


MEDIUMINT(M) 


3 bytes 


If unsigned, stores values from 0 to 16777215; 
otherwise, from -8388608 to 8388607. 


INT(M) 


INTEGER(M) 


4 bytes 


If unsigned, stores values from 0 to 4294967295; 
otherwise, from -2147483648 to 2147483647. 


BIGINT(M) 


8 bytes 


If unsigned, stores values from 0 to 
18446744073709551615; otherwise, 
from -9223372036854775808 to 
9223372036854775807. You may experience 
strangeness when performing arithmetic with 
unsigned integers of this size due to limitations in 
your operating system. 


FLOAT ( preci s i on ) 


4 or 8 bytes 


Where precision is an integer up to 53. If precision 
<= 24, converted to a FLOAT; if precision > 24 and 
<= 53, converted to a DOUBLE. Provided for Open 
DataBase Connectivity (ODBC) compatibility; 
in general, use the normal MySQL FLOAT and 
DOUBLE types. 


FLOAKM, D) 


4 bytes 


Single-precision floating-point number. 


D0UBLE(M, D) 


DOUBLE PRECISION, 
REAL 


8 bytes 


Double-precision floating-point number. 


DEC IMAL( M , D ) 


DEC, NUMERIC, FIXED 


M+1 or M+2 bytes 


An unpacked floating-point number that is stored 
like a CHAR. Used for small decimals, such as 
money. 


DATE 


3 bytes 


Displayed in the format YYYY-MM-DD. 


DATETIME 


8 bytes 


Displayed in the format YYYY-MM-DD HH:MM:SS. 


TIMESTAMP 


4 bytes 


Since MySQL 4.1, can no longer set display size. 
Displayed in the same format as DATETIME. 


TIME 


3 bytes 


Displayed in the format HHH : MM : SS where HHH is 
a value from -838 to 838. This allows a TIME value 
to represent an elapsed time between two events. 


YEAR 


1 byte 


Displayed in the format YYYY, which is a value 
from 1901 to 2155. To use an earlier date, you 
should use a TINY I NT type. 



continued 
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TABLE 15-1 



(continued) 



Name and Aliases 



Storage size 



Usage 



charcm; 



M bytes 



Fixed in length. If your string is not long enough, it 
will be padded with spaces at the end. M must be 
<= 255. 



VARCHAR(M) Up to M bytes Variable in length. M must be <= 255. 



BINARY(M) 




Up to M bytes 


Stores byte strings. 


VARBINARY(M) 




Up to M bytes 


Similar to VARCHAR. Stores byte strings. 


TINYBLOB or Til 


JYTEXT 


Up to 255 bytes 


TI N Y B LOB is case-sensitive for sorting and 
comparison; TINYTEXT is case-insensitive. 


BLOBorTEXT 




Up to 64KB 


BLOB is case-sensitive for sorting and comparison; 
TEXT is case-insensitive. 


MEDIUMBLOB or 
MEDI UMTEXT 




Up to 16MB 


MEDIUMBLOB is case-sensitive for sorting and 
comparison; MEDIUMTEXT is case-insensitive. 


LONGBLOB or LOT 


JGTEXT 


Up to 4CB 


LONGBLOB is case-sensitive for sorting and 
comparison; LONGTEXT is case-insensitive. 


ENUM(val uel , 
. . . val ueN ) 




1 or 2 bytes 


Up to 65535 distinct values. 


SET( val uel , . . 
val ueN ) 




Up to 8 bytes 


Up to 64 distinct values. 



MySQL Functions 

Table 15-2 includes a recap of the MySQL functions. All arguments in brackets are optional. 



TABLE 15-2 



PHP-MySQL Functions 



Function Name 



Usage 



mysql _af f ected_rows (Clin k_i d] [ 



Use after a nonzero I N S E RT, U P D AT E, or 
DELETE query to check number of rows 
changed. 
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Function Name 


Usage 


mysql_change_user( user , password[ , database] 
[ , 1 ink_id] ) 


rhpnopi; mqpt on pn nnpn link 

V^IICllltlCD IVIy JWL LlDC-l \Jl 1 till UUCI 1 lllllx. 


mysql. 


_cl ose( [1 i nk_i d] ) 


Closes the identified link (usually 

UI II ItrLcsScll y ) . 


mysql_connect([host][:port][:socket][, 
username] [ , password]) 


Opens a link on the specified host, port, 
socket; as specified user with password. 

All srnnmontc am r\ inn a 
All dl tlUI I Id ILd die UUUUMdl. 


mysql. 


_create_db(db_rame[ , Tin k id]) 


("rp^tpQ t\ npw N/^v^fil rl^t^iK^iQP on thp 
Li catcs el iicvv iviyj^yi_ ualciijajc \J 1 1 Li ic 

host associated with the nearest open 
link. 


mv s n 1 


data seekCresult id, row num) 


Moves internal row pointer to specified 
row number. Use a fetching function to 
return data from that row. 


mysql . 


„drop_db(db_name[ , link_id]) 


Drops specified MySQL database. 


mysql. 


_errno( [1 i nk_i d] ) 


Returns ID of error. 


mysql . 


_error( [1 i nk_i d] ) 


Returns text error message. 


mysql. 


_f etch_a rray ( resul t_i d [ , resul t_type] ) 


Fetches result set as associative array. 
Result type can be M Y S Q L_A S S 0 C, 
MYSQL_NUM, or MYSQL_BOTH (default). 


mysql. 


_f etch_f i el d ( resul t_i d [ , fi el d_offset] ) 


Returns information about a field as an 
object. 


mysql. 


_f etch_l engths( resul t_i d ) 


Returns length of each field in a result set. 


mysql . 


_f etch„ob j ect ( resul t_i d[ , resul t_type] ) 


Fetches result set as an object. See 
mysql _fetch_a rray for result types. 


mysql. 


_f etch_row( resul t_i d ) 


Fetches result set as an enumerated array. 


mysql. 


_f i el d_name (resul t_i d , fi el d_i ndex) 


Returns name of enumerated field. 


mysql. 


_f i el d_seek( resul t_i d , fi el d_offset ) 


Moves result pointer to specified field 
offset. Used with mysql_f etch_f i el d. 


mysql. 


_f i el d_tabl e ( resul t_i d , fi el d_of f set ) 


Returns name of specified field's table. 


mysql. 


_f i el d_type ( resul t_i d , f i el d_of f set ) 


Returns type of offset field (for example, 
TINYINT, BLOB, VARCHAR). 


mysql. 


_f i el d_f 1 ags ( resul t_i d , f i el d_of f set ) 


Returns flags associated with enumerated 
field (for example, NOT NULL, AUT0_ 
INCREMENT, BINARY). 



continued 
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1 (continued) 


Function Name 


Usage 


mysql _f i el d_l en ( resul t_i d , f i el d_of f set ) 


Returns length of enumerated field. 


mysql _f ree„resul t ( resul t_i d ) 


Frees memory used by result set (usually 
unnecessary). 


mysql _i nsert_i d ( [ 1 i n k_i d] ) 


Returns AUT0_I NC REM ENTED ID of 
INSERT; or FALSE if insert failed or last 
query was not an insert. 


my sql _1 i st_f i el ds ( da t a base , tablet, link_id]) 


Returns result ID for use in mysql _ 
field functions, without performing an 
actual query. 


my sql _1 i st_dbs ( [ 1 i nk_i d] ) 


Returns result pointer of databases 
on my s q 1 d . Used with my s q 1 _ 
tabl ename. 


my sql _1 i st_tabl es(database[, li nk_i d] ) 


Returns result pointer of tables 
in database. Used with my s q 1 _ 
tabl ename. 


mysql _num_fi el ds ( resul t_i d ) 


Returns number of fields in a result set. 


my sql _num_rows (resul t_i d ) 


Returns number of rows in a result set. 


mysql_pconnect([host][:port][:socket][, 
username][, password]) 


Opens persistent connection to database. 
All arguments are optional. Be careful — 
my sql _cl ose and script termination will 
not close the connection. 


my sql _query ( query_stri ng [ , Tin k_i d] ) 


Sends query to database. Remember to 
put the semicolon outside the double- 
quoted query string. 


mysql_resul t( resul t_i d , row_id, field_ 
i denti tier) 


Returns single-field result. Field 
identifier can be field offset (0), field 
name (Fi rstName) or table-dot name 
(myf i el d .mytabl e). 


my sql _sel ect_db ( database [ , 1 i n k_i d] ) 


Selects database for queries. 


mysql_tablena me (resul t_i d , tabl e_i d ) 


Used with any of the my s q 1 _1 i s t 
functions to return the value referenced 
by a result pointer. 
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Summary 

PHP's MySQL and MySQL Improved functions are easy to use, if sometimes named confusingly 
Each instance of a PHP/MySQL interaction must have a connection, a database select, and a query or 
command that returns a result identifier. The result identifier is like an ATM receipt that reports on 
the success or failure of an operation. 

If data is returned after a SELECT statement, one of the PHP/MySQL fetching functions must also 
be employed. Data pulled from a MySQL database exists in a kind of limbo until one of the fetching 
functions is applied to the result set. If you wish to loop through the result set again, you can use 
mysql_data_seek( ) to reset the row pointer to zero. 

PHP also has a large number of functions that return data about the database itself or about a par- 
ticular operation. Two of the most common are mysql_num_rows ( ) , which returns the number 
of rows in a result set, and my s q 1 _i n s e rt_i d ( ) , which returns the ID of the proximate I N S E RT 
operation. 

PHP handles much of the MySQL connectivity for you without requiring specific link identifiers or 
result pointers. The exception comes when you need multiple database connections on the same web 
page. In this case, you use exactly the same functions and syntax but simply pass the correct link 
identifier with most commands. 

We do not personally recommend creating MySQL databases with PHP front ends. 
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Much of the point of PHP is to help you translate between a back- 
end database and its frontend presentation on the web. Data can 
be viewed, added, removed, and tweaked as a result of your web 
user's keystrokes and mouse clicks. 

For most of this chapter, we restrict ourselves to ways to use PHP to look at 
the contents of a database without altering it, using only the SELECT state- 
ment from SQL and displaying the results in HTML tables. We use a single 
database example to show different strategies, including some handy reus- 
able functions. Finally, we look at code to create the sample data shown in 
the display examples, using the I NSERT statement. 

The two big productivity points from this chapter are: 

■ Reuse junctions in simple cases. The problem of database table 
display shows up over and over in database-enabled site design. 
If the display is not complicated, you should be able to throw the 
same simple function at the problem rather than reinventing the 
wheel with each PHP page you write. 

■ Choose between techniques in complex cases. You may find yourself 
wanting to pull out a complex combination of information from 
different tables (which, of course, is part of the point of using a 
relational database to begin with). You may not be able to map 
this onto a simple reusable function, but there aren't that many 
novel solutions either — get to know the alternatives, and you can 
decide how to trade off efficiency, readability, and your own effort. 



IN THIS CHAPTER 



HTML tables and MySQL tables 
Complex mappings 
Creating the sample tables 



j J 01 r 



f This chapter uses the MySQL database and functions exclusively, 
' but the display strategies should be directly transferable to 
almost any SQL-compliant database supported by PHP. 
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HTML Tables and Database Tables 



First of all, some terminology — unfortunately, both relational databases and HTML scripting use 
the term table, but the term means very different things in the two cases. A database table persis- 
tently stores information in columns, which have predefined names and types so that the informa- 
tion in them can be recovered later. An HTML table is a construct that tells the browser to lay out 
arbitrary HTML contents in a rectangular array in the browser window. We'll try to always make it 
clear which kind of table we are talking about. 

One-to-one mapping 

HTML tables are really constructed out of rows (the <TRX/TR> construct), and columns have no 
independent existence — each row has some number of table datum items (the <TDX/TD> con- 
struct), which will produce a nice rectangular array only if there are the same number of TDs for 
every TR. (There is no corresponding <TC> construct that lets you display by column first.) By con- 
trast, fields (aka columns) in database tables are the more primary entity — defining a table means 
defining the fields, and then you can add as many rows as you like. In this chapter, we will focus 
on printing out tables and queries in such a way that each database field prints in its own HTML 
column, simply because there are usually more database rows than database fields, and people are 
more used to up-and-down scrolling than left-to-right scrolling. If you find yourself wanting to map 
database fields to HTML rows, it is a simple inversion exercise. 

The simplest case of displaying a table is the one in which the structure of a database table or query 
does correspond to the structure of the HTML table we want to display — the database entity has m 
columns and n rows, and we'd like to display an m-by-n rectangular grid in the user's browser win- 
dow, with all the cells filled in appropriately. 

Example: A single-table displayer 

So let's write a simple translator that queries the database for the contents of a single table and dis- 
plays the results onscreen. Here's the top-down outline of how the code will get the job done: 

1. Establish a database connection. 

2. Construct a query to send to the database. 

3. Send the query and hold on to the result identifier that is returned. 

4. Using the result identifier, find out how many columns (fields) there are in each row. 

5. Start an HTML table. 

6. Loop through the database result rows, printing a <TRX/TR> pair to make a correspond- 
ing HTML table row. 

7. In each row, retrieve the successive fields and display them wrapped in a <TDX/TD> pair. 

8. Close off the HTML table. 

9. Close the database connection. 
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Finally, we'd like to wrap all the preceding steps up into a handy function that we can use whenever 
we want to. Also, for reasons of efficiency, we don't want to include the first and last steps of creating 
and closing the database connection in the function — we may want to use such a function more 
than once per page, and it wouldn't make sense to open and close the connection each time. Instead, 
we'll assume that we have a connection already and pass the connection to the function along with 
the table name. 

Such a function is shown in Listing 16-1, embedded in a complete PHP page that uses the function 
to display the contents of a couple of tables. 



LISTING 16-1 



A table displayer 

<?php 

i ncl ude ( " / home/phpbook/phpbook- va rs . i nc " ) ; 

$gl oba l __dbh = mysql_connect( Ihostname , $username, $password); 
my s q 1 _s e 1 e c t_d b ( $ d b , $global_dbh) ; 

function di spl ay_db_tabl e( $ t a b l ename , $connection) 

{ 

$query_stri ng = "SELECT * FROM $tabl ename " ; 
$result_id = mysql_query ( $query_stri ng , $connection); 
$col umn_count = my sql _num_f i el ds ( $ resul t_i d ) ; 

print ( "<TABLE B0RDER=l>\n " ) ; 
while ($row = mysql_f etch_row( $ resul t_i d ) ) 
I 

print("<TR ALIGN = LEFT VALIGN=TOP>" ) ; 
for ( $col umn_num = 0 ; 

$col umn_num < $col umn_count ; 

$col umn_num++) 
print("<TD>$row[$col umn_num] </TD>\n " ) ; 
print("</TR>\n"); 

) 

print( "</TABLE>\n" ) ; 

1 

?> 

<HTML> 
<HEAD> 

<TITLE>Cities and countri es</TITLE> 

</HEAD> 

<B0DY> 

<TABLEXTRXTD> 

<?php di spl ay_db_tabl e( "country " , $ g 1 oba 1 _dbh ) ; ?> 
</TDXTD> 
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<?php di spl ay_db_tabl e( "ci ty" , $global_dbh); ?> 
</TD></TRX/TABLE></BODYX/HTML> 



Some things to notice about this script: 

■ Although the script refers to specific database tables, the d i s p 1 a y_d b_t a b 1 e ( ) function 
itself is general. You could put the function definition in an i ncl ude file and then use it 
anywhere on your site. 

■ The first thing the script does is load in an i n c 1 u d e file that contains variable assignments 
for the database name, database username, and database password. It then uses those vari- 
ables to connect to MySQL and then to choose the desired database. (The fact that this file 
is located outside the publicly available web hierarchy makes it slightly more secure than 
just including that information in your code.) 

■ In the function itself, we chose to use awhile loop for printing rows and a f o r loop to 
print the individual items. We could as easily have used a bounded for loop for both and 
recovered the number of rows with mysql„num_rows ( ) . 

■ The main while loop reflects a very common idiom, which exploits the fact that the value 
of a PHP assignment statement is the value assigned. The variable $ row is assigned to the 
result of the function mysql_f etch_row( ) , which will be either an array of values from 
that row or a false value if there are no more rows. If we're out of rows, $ row is false, which 
means that the value of the whole expression is false, which means that the while loop 
terminates. 

■ We put line breaks (\ n) at the end of selected lines, so that the HTML source would have 
a readable structure when printed or viewed as source from the browser. Notice that these 
breaks are not HTML line breaks (<BR>) and do not affect the look of the resulting web 
page. (In fact, if you want to make it annoying for someone else to scrutinize the HTML 
you generate, don't put breaks in at all!) 



The sample tables 

To see the Listing 16-1 script in action, see Figure 16-1, which shows the displayed contents of the 
Country and City sample tables. These tables have the following structure: 

Country : 

ID int ( auto- i ncremented primary key) 
contirent varchar(50) 
countryname varchar(50) 
City: 

ID int ( auto- i ncremented primary key) 
country ID int 
cityname varchar(50) 
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16 



FIGURE 16-1 



A simple database table display 
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Think of these tables as a rough draft of the database for an eventual online almanac. They employ 
our usual convention of always having one field per table called I D, which is a primary key and has 
successive integers assigned to it automatically for each new row. Although you can't tell for sure 
from the preceding description, the tables have one "relation" embodied in their structure — the 
country ID field of the City table is matched up with the I D field of the Country table, represent- 
ing which country the city belongs to. (If you were designing a real almanac database, you would 
want to take this one step further and break the Country table into a relational pair of Country and 
Continent tables.) 

p rj rj'£J£J_, T° see how we created these tables and populated them with sample data, see the 

— "Creating the Sample Tables" section at the end of this chapter. 

Improving the displayer 

Our first version of this function has some limitations: It works with a single table only, does no 
error-checking and is very bare-bones in its presentation. We'll address these problems one by one 
and then fix them in one fell revision. (If you want to look ahead, the new-and-improved version of 
the function is in Listing 16-2.) 
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Displaying column headers 

Our first version of a database table displayer simply displays all the table cells, without any labeling 
of what the different fields are. It's conventional in HTML to use the <TH> element for column and/ 
or row headers — in most browsers and styles, this displays as a bold table cell. One improvement 
we can make is to optionally display column headers that are based on the names of the table fields 
themselves. To actually retrieve those names, we can use the function mysql_f i el d_name ( ) . 

Error checking 

Our original version of the code assumes that we have written it correctly and also that our database 
server is up and functioning normally — if either of these is not the case, we will run into puzzling 
errors. We can partially address this by appending a call to di e ( ) to the actual database queries 
— if they fail, an informative message will be printed. This is a reasonable approach for such a small 
example, but as projects get larger it is better to use the exception-handling capability introduced 
back in PHP5. 

j" ^'1^ Cj£)~£)-'I J ^ f a0 ' ntroc ' uct ' on to exce ption handling, see Chapter 30. 

Cosmetic issues 

Another source of dissatisfaction with our simple table-displayer is that it always has the same look. 
It would be nice, at a minimum, to control whether table borders are displayed. The simple solution 
we will use in our new function is just to permit passing in a string of arguments that will be spliced 
into the HTML table definition. This is a pretty crude form of style control that style sheet propo- 
nents would discourage, but it will permit us to directly specify some elements of the table's look 
without writing an entirely new function. 

Displaying arbitrary queries 

Finally, it would be nice to be able to exploit our relational database and display the results of com- 
plex queries rather than just single tables. Actually, our single-table displayer has an arbitrary query 
embedded in it — it just happens that it is hardcoded as select * from table, where table is the 
supplied table name. So let us transform our simple table displayer into a query displayer and then 
recreate the table displayer as a simple wrapper around the query displayer. These two functions, 
complete with the cosmetic improvements and better error checking, are shown in Listing 16-2. 



LISTING 16-2 



A query displayer 

<?php 

include("/home/phpbook/phpbook-vars.inc"); 

$global_dbh = mysql_connect ( $hostname , $username, $password) 
or d i e ( " Could not connect to database"); 
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my sql_sel ect_db ( $db, $global_dbh) 
or die("Could not select database"); 

function di spl ay_db_query ( $query_stri ng , $connection, 

$header_bool , $tabl e_pa rams ) 

{ 

// perform the database query 

$result_id = mysql_query ( $query_stri ng , $connection) 

or di e( "di spl ay_db_query : " . mysql_error( ) ) ; 

// find out the number of columns in result 
$col umn_count = my sql_num_f i el ds ( $ resul t_i d ) 

or di e( "di spl ay_db_query : " . mysql„error( ) ) ; 

// TABLE form includes optional HTML arguments passed 
// into function 

pri nt( "<TABLE $tabl e_pa rams >\n"); 

// optionally print a bold header at top of table 

i f ( $header_bool ) 

( 

print("<TR>") ; 

for ($column_num = 0; 

$column_num < $col umn_count ; 

$col umn_num++) 

{ 

$field_name = 

mysql_f i el d„name ( $ resul t_i d , $col umn„num ) ; 
print( "<TH>$field_name</TH>" ) ; 

) 

print("</TR>\n"); 

} 

// print the body of the table 

while ($row = mysql _fetch„row( $ resul t_i d ) ) 

{ 

print("<TR ALIGN=LEFT VALIGN=T0P>" ) ; 
for ( $col umn_num = 0 ; 

$column_num < $col umn__count ; 

$col umn_num++) 

{ 

print("<TD>$row[$col umn_num] </TD>\n " ) ; 

} 

print("</TR>\n"); 

} 

print( "</TABLE>\n" ) ; 



function di spl ay_db_tabl e( $tabl ename , $connection, 

$header_bool , $tabl e_pa rams ) 



243 



Part II 



MySQL Database Integration 



{ 

$query_stri ng = "SELECT * FROM $tabl ename" ; 
di spl ay_db_query ( $query_stri ng, $connection, 

$header_bool , $tabl e_params ) ; 

} 

?> 

<HTMLXHEADXTITLE>Countries and ci ti es</TITLEX/HEAD> 
<B0DY> 

<TABLEXTRXTD> 

<?php di spl ay_db_t a bl e( "country" , $global_dbh, 

TRUE, " B0RDER=2 " ) ; ?> 

</TDXTD> 

<?php di spl ay_db_tabl e( "ci ty" , $global_dbh, 

TRUE, " B0RDER=2 " ) ; ?> 
</TDX/TRX /TAB LEX /BODYX/ HTML) 



The result of using this code on the same database contents is shown in Figure 16-2. The only vis- 
ible difference is the column header. Splitting the functions apart means that we also have a new 
function in our bag of tricks — we could do the same kind of display with an arbitrary query string 
that joins data from different tables. 



FIGURE 16-2 
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So far in this chapter, we've enjoyed a very nice and simple-minded correspondence between query 
resultsets and HTML tables — every row in the resultset corresponds to a row in the table, and 
the structure of the code is simply two nested loops. Unfortunately, life isn't often this simple, and 
sometimes the structure of the HTML table we want to display has a complex relationship to the 
relational structure of the database tables. 



Views and Stored Procedures 

Our query displayer assumes a particular division of labor between the PHP code and the database system 
itself — the PHP code sends off an arbitrary query string, which the database responds to by setting up a 
resultset. In particular, this means that the database system has to parse that query and then figure out the best 
way to go about retrieving the results. This is part of what can make querying a database a mildly expensive 
operation. 

In cases where your code may construct novel queries on the fly, this is the best you can hope for. However, 
some databases offer ways to set up queries in advance, which gives the database system a chance to preop- 
timize how it handles the query. One such construct is called a view under MS SQL Server and some other 
RDBMSs — after you have set up a query as a named view, it can be treated just like a real table. A related 
idea is the stored procedure, which is like a view that also accepts runtime arguments that are spliced into the 
query. In general, if you realize that you are suffering from slow query performance, you may want to investigate 
what similar optimizations your particular RDBMS makes available. 



Multiple queries versus complex printing 

Let's say that, rather than displaying our sample Ci ty and Country tables individually, we want to 
match them up in a tabular display. 

We can easily write a SELECT statement that joins these tables appropriately: 

SELECT country . conti nent , country . countryname , 

ci ty . ci tyname 
FROM country, city 
WHERE ci ty . count ry I D = country. ID 
ORDER BY continent, countryname, cityname 

Now, this would be a handy place to use our query-displayer function — all we have to do is send 
it the preceding statement as a string, and it will print out a table of cities matched up with their 
continents and countries. However, if we do this, we will see an individual HTML table row for each 
city, and the continent and country will print each time — for example, we'll see North America 
printed several times. Instead, what if we want one name matched with many titles? This is a case 
where the structure of what we print differs from the structure of the most convenient query. 



245 



Part II 



MySQL Database Integration 



If we want to do a more complex mapping, we have a choice: We can throw database queries at the 
problem, or we can write more complex display code. Let's look at each option in turn. (For each of 
these examples, we'll be moving away from the reusable generality of the functions we wrote earlier 
toward functions that address a particular display problem.) 

A multiple-query example 

If we want to print just one HTML row per country, we can make a query for the countries and then 
make another query for the relevant cities in each trip through a country row. A function written 
using this strategy is shown in Listing 16-3. 



LISTING 16-3 



A display with multiple queries 

<?php 

i ncl ude ( " /home/phpbook/phpbook- va rs . i nc" ) ; 
/* open database connection */ 

$ g 1 oba 1 _dbh = mysql_connect ( $hostname , $username, $password) 

or die("Could not connect to database"); 
mysql_sel ect_db( $db, $global_dbh) 
or die("Could not select database"); 

function displ ay_ci ti es ( $db_connecti on ) 
{ 

/* Displays table of cities and countries */ 
$country_query = "SELECT id, continent, countryname 
FROM country 

ORDER BY continent, countryname"; 

$country_resul t = 

mysql_query ( $country_query , $db_connecti on ) ; 

/* begin table, print hard-coded table header */ 
pri nt ( " <TAESLE B0RDER=l>\n" ) ; 
print ( "<TRXTH>Continent</THXTH>Country</TH> 
<TH>Cities</THX/TR>") ; 

/ * loop through countries */ 

while ( $country_row = my sql _f etch_row( $count ry_resul t ) ) 

I 

/* set up country info */ 
$country„id = $country_row[0] ; 
Icontinent = $country_row[l] ; 
$country_name = $country_row[2] ; 

print("<TR ALIGN=LEFT VALI GN=T0P> " ) ; 
print ( "<TD>$continent</TD>" ) ; 
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print ( "<TD>$country_name</TD>" ) ; 

/* begin table cell for city list */ 
print( "<TD>" ) ; 

$city_query = "select cityname from city 

where countrylD = $country_id 
order by cityname"; 

$city_result = 

my sql_query ( $ci ty_query , $db_connecti on ) 
OR die(mysql_error()); 
/* loop through cities */ 

while ($city_row = mysql_f etch„row( $ci ty„resul t ) ) 
( 

$city_name = $ci ty_row[0] ; 
pri nt( "$ci ty_name<BR>" ) ; 

) 

/* close city cell and country row */ 
print("</TDX/TR>") ; 

) 

print( "</fABLE>\n" ) ; 

1 

?> 

<HTML> 
<HEAD> 

<TITLE>Cities by Country</TITLE> 

</HEAD> 

<B0DY> 

<?php 

di spl ay_ci ties($global_dbh) ; 

?> 

</B0DY> 
</HTML> 



The strategy is appealingly simple: There is an outer loop that uses one query to proceed through 
all the countries, saving the country's name and the primary I D field of each country row. Then for 
each country, the I D field is used to look up all the cities belonging to that country. Notice the trick 
of embedding the $countryid variable in the inner query — the query string sent is actually differ- 
ent on each iteration through the country loop. 

Simple? Yes. Efficient? Probably not. This code makes a separate city query for each country. If there 
are 500 countries in the database, this function will make 501 separate database queries (the extra 
one being the enclosing country query). 

Your mileage will vary according to how efficient your particular database is in parsing queries and 
planning query retrieval, but the sum of these queries will certainly take more time than the simple 
query we started this section with. 
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A complex printing example 

Now let's solve exactly the same problem, but using a different strategy. Instead ol making multiple 
queries, we will make a single query and print the resulting rows selectively, so that each HTML 
table row corresponds to more than one database row (see Listing 16-4). The resulting browser dis- 
play is exactly the same as in the previous example. 



LISTING 16-4 



A complex display with a single query 

<?php 

include("/home/phpbook/phpbook-vars.inc"); 

/* open a single DB connection for this page */ 

$global_dbh = mysql_connect ( $hostname , $username, $password) 

or die("Could not connect to database"); 
mysql_sel ect_db( $db, $global_dbh) 

or die("Could not select database"); 

function displ ay_ci ti es ( $db_connecti on ) 
{ 

/ * print table of countries and their cities, 
selectively printing only one HTML table row 
per country */ 
$query = "SELECT country. id, 

country. continent, country. country name, 

ci ty . ci tyname 

FROM country, city 

WHERE country. id = ci ty . country I D 

ORDER BY country . conti nent , 

country. country name, 
ci ty . ci tyname " ; 

$result_id = 

mysql_query ( $ query , $db_connecti on ) 
OR die(mysql_error($query)); 

/* begin table, print hard-coded table header */ 
pri nt( "<TABLE B0RDER=l>\n" ) ; 
print ( "<TH>Continent</THXTH>Country</TH> 
<TH>Cities</THX/TR>") ; 

/* Initialize the ID for the "previous" country. 
We will rely on the fact that Country. ID is 
numbered beginning with 1, so a previous ID 
value of zero means that the current country 
is the first */ 

$ol d_country_i d = 0; 
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/* loop through result rows (one per city) */ 
while ($row_array = my sql _f etch_row( $ resul t_i d ) ) 
{ 

$country_id = $row„array [0] ; 
/* if we have a new country */ 
if ($country_id != Sol d_country_i d ) 
{ 

/* set up country info */ 
Scontinent = $row_array[l] ; 
$country_name = $row_array [2] ; 

/* if there was a previous country 

close the city datum and country row */ 
if ( $ol d_country_i d != 0) 
print("</TDX/TR>\n") ; 

/* start a row for the new country, 

and begin the city table datum */ 
print("<TR ALIGN=LEFT VALIGN=T0P>" ) ; 
pri nt( "<TD>$conti nent</TD>" ) ; 
print( "<TD>$country_name</TDXTD>" ) ; 

/* the new country is no longer new */ 
$ol d_country_i d = $country_id; 

) 

/* the only thing that is printed for every result 

row is the name of a city */ 
$city_name = $row_array[3] ; 
pr i nt ( " $ci ty_name<BR> " ) ; 

} 

/* close off final country and table */ 
print( "</TDX/TRX/TABLE>" ) ; 

} 

?> 

<HTMLXHEADXTITLE>Cities by Count ry</TITLEX/HEAD> 
<B0DY> 

<?php displ ay_ci ties($global_dbh); 
?> 

</BODYX/HTML> 



This code is somewhat tricky — although it goes through the result rows in order, and everything 
it prints is grabbed from the current row, it prints countries only when their values have changed. 
(Continents are still printed redundantly.) 

The change in a country is detected by monitoring the I D field of the country row. A country 
change is also a signal to print out the HTML necessary to close off the preceding table row and start 
a new one. Finally, the code must handle printing the HTML necessary to start the first row and end 
the last one. 
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Creating the Sample Tables 

Now we will show you the PHP/MySQL code we actually used to create the sample tables. (Such 
data might more normally be created by interacting only with MySQL, but we decided to respect our 
book's title by doing it from PHP.) The code (shown in Listing 16-5) is a special-purpose, one-time 
hack, not a model of style, but it has useful examples of using the SQL I N S E RT statement. 



LISTING 16-5 



Creating the sample tables 

<?php 

i ncl ude ( " /home/phpbook/phpbook- va rs . i nc" ) ; 

$ g 1 oba 1 _dbh = mysql_connect ( $hostname , $username, $password) 
or die("Could not connect to database"); 

mysql_sel ect_db( $db, $global_dbh) 

or die ("Could not select databased"); 

function add_new_country ( $ d b h , $continent, $countryname , 

$ci ty_a rray ) 



$country_query = 

"INSERT INTO country (continent, countryname) 
VALUES ( ' $conti nent ' , ' $countryname ' ) " ; 
$result_id = my sql _query ( $count ry_query ) 

OR di e ( $ count ry_query . mysql_error( ) ) ; 
if ($result_id) 
( 

IcountrylD = mysql_i nsert_i d( $dbh ) ; 
for ($city = current( $ci ty_array ) ; 
$ci ty ; 

$city = next ( $ci ty_a rray ) ) 

{ 

$city_query = 

"INSERT INTO city (countrylD, cityname) 
VALUES (IcountrylD, '$city')"; 
mysql_query ( $ci ty_query , $ d b h ) 

OR di e ( $ci ty_query . my sql _error ( ) ) ; 

1 

1 

} 

function popul ate_ci ti es„db( $dbh ) 
{ 

/* drop tables if they exi st - permi ts function to be 
tried more than once */ 
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mysql_query ( "DROP TABLE city", $dbh); 
mysql_query ( "DROP TABLE country", $dbh); 

/* create the tables */ 
mysql_query( "CREATE TABLE country 

(ID int not null auto_i ncrement primary key, 
continent varchar(50), 
countryname va rcha r ( 50 ) ) " , 
$dbh) 

OR die(mysql_error()); 
mysql_query( "create table city 

(ID int not null auto_i ncrement primary key, 
countrylD int not null, 
cityname varchar(50) ) " , 
$dbh) 

OR die(mysql_error()); 

/* store data in the tables */ 
add_new_country ( $dbh , 'Africa', 'Kenya', 

array( 'Nairobi ' , 'Mombasa' , 'Meru' )) ; 
add_new_country ( $dbh , 'South America', 'Brazil', 

array('Rio de Janeiro', 'Sao Paulo', 

'Salvador', 'Belo Hori zonte ' ) ) ; 
add_new_country ( $dbh , 'North America', 'USA', 

array (' Chi cago ' , 'New York', 'Houston', 'Miami')); 
add_new_country ( $dbh , 'North America', 'Canada', 

array( 'Montreal ' , 'Windsor' , 'Winnipeg' ) ) ; 

pri nt( "Sampl e database created<BR> " ) ; 

1 

?> 

<HTMLXHEADXTITLE>Creating a sample database</TITLEX/HEAD> 
<B0DY> 

<?php popul ate_ci ti es_db( $gl obal _dbh ) ; ?> 
</BODYX/HTML> 



You should be able to use this code to recreate the sample database on your development machine, 
assuming that you have PHP and MySQL configured, and an appropriately located file called ph p - 
book-vars.inc containing username, password, and database-name strings. 

Just as in the display examples, this code sends off query strings (with embedded variables), but this 
time the queries are I N S E RT statements, which create new table rows. For the most part, the data 
inserted is just string data passed in to the function, although we chose to pass in an arbitrary num- 
ber of cities per country by using an array. 

The only tricky thing in creating these sample tables is setting up the relational structure. We want 
each city row to have an appropriate countrylD, which should be equal to the actual I D of the 
appropriate row from the country table. However, these country IDs are automatically assigned 
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in sequence by MySQL and are not under our control. How can we know the right countrylD to 
assign? The answer is in the incredibly handy function my s q 1 _i n s e r t_i d ( ) , which recovers the 
I D associated with the last I NSERT query made via the given database connection. We insert the 
new country, recover the I D of the newly created row, and then use that I D in our city insertion 
queries. 



Summary 

Database interaction is one of the areas where PHP really shines. One very common use for data- 
base-enabled web code is simply to display database contents attractively. One approach to this kind 
of display is to map the contents of database tables, or SELECT statements, to corresponding HTML 
table elements. 

When the mapping is simple enough, you can employ reusable functions that take arbitrary table 
names, or SELECT statements, and display them as a grid. When you need a more complicated 
combination of information from relational tables, you probably need a special-purpose function, 
but certain tricks recur there as well. One such trick is to craft a SQL statement that returns all the 
information you need, in the order you want, and selectively print only the nonredundant portions. 

Near the end of this chapter, you saw a quick example of populating a set of database tables using 
INSERT statements. Aside from that, all the techniques in this chapter were read-only and do not 
modify the contents of databases at all. In Chapter 17, you'll see how you can get a more intimate 
connection to your database by combining SQL queries with HTML forms. 
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and Databases 



Form handling is one of PHP's very best features. The combination 
of HTML to construct a data-input form, PHP to handle the data, 
and a database server to store the data lies at the heart of all kinds of 
supremely useful web tasks. 



HTML Forms 



You already know most of what you need to make good forms to be handled 
by PHP and a database. There are a few PHP-specific points to brush up on: 

■ You must use extra caution when using any data that comes from 
a visitor's web browser. It may seem like common sense, but there 
are still too many PHP programs that don't escape incoming data 
from a web form or from a web browser (or anywhere). Never use 
unfiltered data in a database query. 

■ Always, always, always use a NAME for every data entry element 
(INPUT, SELECT, TEXTAREA, and so on). These NAME attributes 
will become PHP variable names — you will not be able to access 
your values if you do not use a NAME attribute for each one. If 
your WYSIWYG editor doesn't allow you to do this, you'll need to 
remember to add these NAME attributes by hand. 

■ A form field NAME does not need to be the same as the correspond- 
ing database field name. 

■ The VALUE can be set to data you wish to display in the form. 

■ Remember that you can pass hidden variables from form to form 
(or page), using the HIDDEN data entry elements. This practice has 



IN THIS CHAPTER 



Understanding HTML forms 
Submitting data via forms 
Self-submitting forms 
Editing data with an HTML form 
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negative security implications, so don't use it to store sensitive data and always validate the 
data you receive in a HIDDEN element; never trust it to be what you expect. 

rj r \"~ rj r'r See Chapter 6 for more information on how to format an HTML form for use with PHP. 

Basic Form Submission to a Database 

Submitting data to a database via an HTML form is straightforward if the form and form handler 
are two separate pages. Listing 17-1, news 1 etter_s ignup.html, is a simple form with only one 
input field. 



LISTING 17-1 



A simple form (newsletter_signup.html) 

<HTML> 
<HEAD> 

<STYLE TYPE="text/css"> 

<!-- 

BODY, P {color: black; font-family: verdana; 

font-size: 10 pt) 

HI (color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 CELLPADDI NG=10 WIDTH=100%> 
<TR> 

<TD BGC0L0R="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=T0P WIDTH=83%> 
<Hl>Newsl etter sign-up form</Hl> 

<P>Enter your email address and we will send you our 
weekly newsl etter . </P> 

<F0RM METH0D="post" ACTI0N="formhandl er . php"> 
<INPUT TYPE="text" SIZE=25 NAME="emai 1 "> 
<BRXBR> 

<INPUT TYPE="submit" NAME="submi t" VALUE="Submi t"> 

</F0RM> 

</TD> 

</TR> 

</TABLE> 

</B0DY> 
</HTML> 
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Figure 17-1 shows the result of the preceding code sample, a basic form to insert data into a database. 
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FIGURE 17-1 



A form to insert data into a database 



Manila [Build ID: 20020510061 


HESQI 


. File Edit View Go Bookmarks Tools Window Help Debug 0[A 


£^ I ^ hti p -l/l o ca Ihost'ne wsl effe i stgiu | Search [ 




[ v jUnillled) | . IU milled} 


□ 


Newsletter sign-up form 




Enter your email address and we will send you our weekly 


newsletter. 
1 




Su b mil 




Dociiriicnl; Done (D.55 sera) 





You enter the data in the database and acknowledge receipt in the form handler in Listing 17-2, 
which (with great originality) we are calling form hand! er.php. 



LISTING 17-2 



Form handler for newsletter_signup.html (formhandler.php) 

<HTML> 
<HEAD> 

<STYLE TYPE="text/css"> 

<!-- 

BODY, P (color: black; font-family: verdana; 

font-size: 10 pt) 

HI {color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 C E L L PA DD I N G= 1 0 WIDTH=100%> 
<TR> 

<TD BGC0L0R="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=T0P WIDTH=83%> 
<Hl>Newsl etter sign-up form</Hl> 
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<?php 

if ( !$_P0ST[' email '] || $_P0ST[ ' emai 1 ' ] == "" || 

strlen(isset($_POST['email ']) && $_P0ST[ ' emai 1 1 ] > 30) { 
echo ' < P > I s your e-mail address really that long?</P>'; 
1 else ( 

// Open connection to the database 
mysql_connect( "1 ocal host" , "phpuser", "sesame") 
or di e( " Fai 1 ure to communicate with database"); 
mysql_sel ect_db( "test" ) ; 

// Insert email address 

$as_email = mysql_real_escape_st ri ng ( $_P0ST[ ' ema i 1 ' ] ) ; 
$tr_email = trim( $as_emai 1 ) ; 

$query = "INSERT INTO mailinglist (ID, Email, Source) 
VALUESCNULL, ' $tr_email ' , 
'www.example.com/newsletter_signup.html ' ) 

Sresult = mysql_query ( $query ) ; 
if (mysql_affected_rows( ) == 1) ( 

echo '<P>Your information has been recorded .</ P> ' ; 
) else ( 

error_l og(mysql_error()); 

echo ' <P>Somethi ng went wrong with your signup 
attempt. </P>' ; 
} 

} 

?> 

</TD> 

</TR> 

</TABLE> 

</B0DY> 

</HTML> 



Having a separate form and form handler is a very clean design that can potentially be easier to 
maintain. However, there are quite a few things that you might want to do that you can't do easily 
with this model, caused by the difficulty of going back to the form from the form handler and the 
fact that variables are not available to both at the same time. 

For one thing, if something goes wrong with the submission, it's very difficult to redisplay the form 
with the values you just filled in. This is particularly important with something like a user registra- 
tion form, where you might want to check for unique e-mail addresses or matching passwords and 
reject the entire registration with an error message if it doesn't pass the tests. People are going to be 
very annoyed if one little typo causes them to lose all the data that they just filled in — and after one 
or two go-rounds, they will simply stop trying to register. 

The first step to solving all these problems is to combine form and handler into one self-submitting 
PHP script. 
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Self-Submission 

Self-submission refers to the process of combining one or more forms and form handlers in a single 
script, using the HTML FORM standard to submit data to the script one or more times. 

Another situation in which self-submission is a win occurs when you need to submit the same form 
more than once. Say that you are applying for auto insurance online, and you need to give the par- 
ticulars of three or four different cars. It's extra work for the user to submit the form, get a success 
message, and then have to click a button to go back to the form for car #2. This kind of navigation 
problem has no perfect solution, but in situations where there's a high probability of multiple sub- 
missions, self-submission causes fewer clickthroughs for your web users. 

Finally, the separate form and form handler make it difficult to pull data from the database, edit it, 
and submit it — repeating the process however many times it takes for the user to be satisfied. A 
common example of this usage is a form to allow users to change their personal information, such as 
photos and bios, which people often like to fiddle with until they look exactly the way that the users 
want. If you want to make five small incremental edits to your user profile, you aren't going to want 
to go back and forth between the form and form handler 10 times. 

Self-submission is accomplished by the simplest of means: specifying the same script name as the 
ACTION target in the FORM element, like this: 

<F0RM METH0D="P0ST" ACTI0N = "my sel f . php " > 

The single most important thing to remember about self-submitting forms is: The logic comes before 
the display. If you're used to writing separate forms and handlers, this may seem a little counterin- 
tuitive at first — but think of it this way: Because your form will look different or display variables 
based on interactions with the database, obviously these interactions must happen before the HTML 
for the page is output to the browser. After you construct a few self-submitting forms, logic-before- 
display will seem totally natural and painless. 

"~ ' i': ' To use self-submission with controls, you will need to employ a more programmatic PHP- 
writing style — what we term the maximum or medium style. Beginners may find this 
somewhat more difficult than a clear division between the functions of HTML (form display) and PHP 
(form handling). This can be mitigated somewhat by using the heredoc syntax, as we do in many of our 
examples. 

If you're a think-ahead type, by now you're wondering: "But if the logic comes before the display, 
won't my script try to do the database operations before showing me the HTML form in the first 
place?" Good question — and an indication that we need some way to tell the script either "We want 
to see the form now" or "We want to insert data into the database now." This "What am I supposed 
to be doing now?" bit is called a stage variable. It lets you keep track of how many times the form has 
submitted values to itself and, therefore, which stage of a multistep process you have reached. 

The cheapest stage variable to test for is the Submit button. You can name your Submit button and 
give it a value, which will be set as a PHP value only after the form is submitted at least once. The 
easiest way to demonstrate what we're talking about is by rewriting the previous form and form han- 
dler as one self-submitting form, as we do in Listing 17-3. 
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LISTING 17-3 



Unified form and form handler (newsletter_signup.php) 

<?php 

if (isset($_POST['submit']) && $_P0ST[ ' submi t ' ] == 'Submit') ( 
if ( !isset($„POST[ 'email']) || $_P0ST[ ' emai 1 ' ] == "" || 

strlen($_POST['email '] > 30)) { 

Imessage = '<P>There is a problem. Did you enter an email 

address?</P> ' ; 
) else ( 

// Open connection to the database 
mysql_connect( "1 ocal host" , "phpuser", "sesame") 
or die("Failure to communicate with database"); 
mysql_sel ect_db( "test" ) ; 

// Insert email address 

$as_email = my sql „real _escape_st r i ng ( $_P0ST[ ' emai 1 ' ] ) ; 
$tr_email = trim( $as_emai 1 ) ; 

$query = "INSERT INTO mail i n g 1 1st (ID, Email, Source) 
VALUES ( NU LL , '$tr_email', 
' www . exampl e . com/news 1 etter_s i gnup . html ' ) 

$ result = mysql_query ( $query ) ; 
if (mysql_affected_rows ( ) == 1) ( 

Imessage = '<P>Your information has been recorded .</ P> ' ; 

$noform_var = 1; 
} else ( 
error_l og(mysql_error()); 

Imessage = ' <P>Somethi ng went wrong with your signup 
attempt. </P>' ; 
1 

} 

// Show the form in every case except successful submission 
if ( ! i sset ( $nof orm_va r ) ) { 

Sthisfile = " newsl etter_si gnup . php" ; 
Imessage .= <<< EOMSG 
<P>Enter your email address and we will send you our weekly 
newsl etter . </P> 

<F0RM METH0D="post" ACTI0N=" $thi sf i 1 e " > 
<INPUT TYPE="text" SIZE=25 NAME="emai 1 "> 
<BRXBR> 

<INPUT TYPE="submit" NAM E=" submi t" VALUE="Submi t"> 
</F0RM> 
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EOMSG; 

} 

} 

?> 

<HTML> 
<HEAD> 

<STYLE TYPE="text/css"> 

<!-- 

BODY, P (color: black; font-family: verdana; 

font-size: 10 pt) 

HI {color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 C E L L PA DD I N G= 1 0 WIDTH=100%> 
<TR> 

<TD BGC0L0R="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=T0P WIDTH=83%> 

<Hl>Newsl etter sign-up form</Hl> 

<?php echo $message; ?> 

</TD> 

</TR> 

</TABLE> 

</B0DY> 
</HTML> 



The first time you load up this page, you should see a normal HTML form exactly like the one in 
Figure 17-1. If you submit it without any data or with a string that's too long (often a sign of a crack- 
ing attempt), you'll see an error message and the form again. If something goes wrong with the 
database I N S E RT, you'll see an error message and the form again. Only if the I N S E RT completes suc- 
cessfully will you not see the form again — which is the navigation we want because we don't want 
people to sign up for the newsletter more than once. 

In the preceding example, we need to check only for two states of the form (unsubmitted or submit- 
ted), so we can use the Submit button as our stage variable. But what if you want to check for more 
than one state? You need a variable that is capable of taking more than one value. You could either 
give your Submit button different values, which would show up as different labels in the button 
itself, or you could set a hidden variable that is capable of taking more than one value, depending on 
the state. We demonstrate the technique in Listing 17-4, which collects some information and then 
allows you to rate your boss anonymously. 
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LISTING 17-4 



A three-part form (rate_boss.php) 

<?php 

// First set the form strings, which will be displayed 
//in various cases below 

$thisfile = " rate_boss . php" ; //Have to set this for heredoc 
$reg_form = <<< EOREGFORM 

<P>we must ask for your name and email address to ensure that no 

one votes more than once, but we do not associate your personal 

information with your rating. </P> 

<F0RM METHOD="post" ACT 1 0 N= " $ t h i sf i 1 e" > 

Name: < I N PUT TYPE="text" SIZE=25 NAM E=" name "><BRXBR> 

Email: <I NPUT TYPE="text" SI ZE=25 NAME="emai 1"> 

<INPUT TYPE="hidden" NAME="stage" VALUE="regi ster"> 

<BRXBR> 

< INPUT TYPE="submit" NAME="submi t" VALUE="Submi t"> 

</F0RM> 

EOREGFORM: 

$rate_form = <<< EORATEFORM 
<P>My boss is:</P> 

<F0RM METHOD="post" ACTI0N=" $thi sf i 1 e " > 
<INPUT TYPE="radio" NAME=" rati ng" VALUE=1> 
Driving me to look for a new job.<BR> 
<INPUT TYPE="radio" NAME=" rati ng" VALUE=2> 
Not the worst, but pretty bad.<BR> 
<INPUT TYPE="radio" NAME=" rati ng" VALUE=3> 
Just so-so. <BR> 

<INPUT TYPE="radio" NAME=" rati ng" VALUE=4> 
Pretty good.<BR> 

<INPUT TYPE="radio" NAME=" rati ng" VALUE=5> 
A pleasure to work with.<BRXBR> 

Boss's name: < INPUT TYPE="text" SIZE=25 NAME="boss"XBR> 
<INPUT TYPE="hidden" NAME="stage" VALUE="rate"> 
<BRXBR> 

< INPUT TYPE="submit" NAME="submi t" VALUE="Submi t"> 

</F0RM> 

EORATEFORM; 

if (!isset($_POST[ 'submit'])) ( 

// First time, just show the registration form 
Smessage = $reg_form; 
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17 



) elseif (isset(t_POST['submit']) && $_P0ST[ ' submi t ' ] == 'Submit' && $ 
P0ST[ ' stage ' ] == 
'register') ( 

// Second time, show the registration form again on error, 
// rating form on successful INSERT 

if ( ! i sset($_P0ST[ 'name' ] ) || $_P0ST[ ' name ' ] == "" || 
strlen(l_POST['name'] > 30) || ! t_P0ST[ ' emai 1 ' ] || 
$_P0ST[ ' email '] == "" || strl en ( $_P0ST[ 'email ' ] > 30)) ( 

$message = '<P>There is a problem. Did you enter a name and 
emai 1 address?</P> ' ; 

Imessage .= $reg_form; 
I else ( 

// Open connection to the database 
mysql _connect ( "1 ocal host" , "phpuser", "sesame") 
or die("Failure to communicate with database"); 
mysql_select_db("test"); 

// Check to see this name and email have not appeared before 
$as_name = mysql_real_escape_stri ng( $_P0ST[ ' name ' ] ) ; 
$tr_name = t ri m( $as_name ) ; 

$as_email = mysql _real_escape_st ri ng ( $_P0ST[ ' ema i 1 ']) ; 
$tr_email = tri m( $as_ema i 1 ) ; 
Iquery = "SELECT sub_id FROM raters 

WHERE Name = 'ltr_name' 

AND Emai 1 = ' ltr_emai 1 ' 

Iresult = my sql juery ( Iquery ) ; 
if ( mysql_num_rows ( $ resul t ) > 0) ( 
error_J og(mysql„error()); 

Imessage = 'Someone with this name and password has 
already rated . If you think a mistake was made, please email 
hel p@exampl e . com . ' ; 
) else ( 

// Insert name and email address 
$query = "INSERT INTO raters (ID, Name, Email) 
VALUES ( NU LL , '$tr_name', '$tr_email') 

Iresult = mysql _query ( Iquery ) ; 
if (mysql_affected_rows ( ) == 1) ( 

Imessage = $rate_form; 
} else ( 

error_l og(mysql_error()); 

Imessage = ' <P>Somethi ng went wrong with your signup 
attempt. </P>' ; 

Imessage .= lreg_form; 

} 

} 
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) 

1 elseif (isset($_P0ST['submit']) && $_P0ST[ ' submi t ' ] == 'Submit' && $ 
POST['stage'] == 
' rate ' ) { 

// Third time, store the rating and boss's name 

// Open connection to the database 
mysql _connect ( "1 ocal host" , "phpuser", "sesame") 
or di e( " Fai 1 ure to communicate with database"); 
mysql_select_db("test"); 

// Insert rating and boss's name 

$as_boss = mysql_real_escape_stri ng( $_P0ST[ ' boss ' ] ) ; 
$tr_boss = trim( $as_boss ) ; 

$rating = mysql_real_escape_stri ng( $_P0ST[ ' rati ng ' ] ) ; 
$query = "INSERT INTO ratings (ID, Rating, Boss) 
VALUESCNULL, '$rating', '$tr_boss') 

$result = my sql _query ( $query ) ; 
if (mysql_affected_rows( ) == 1) ( 

$message = '<P>Your rating has been submi tted . </P> ' ; 
) else ( 

error_l og(mysql_error()); 

$message = ' <P>Somethi ng went wrong with your rating 
attempt. Try again. </P>'; 
Smessage .= $rate_form; 

} 

} 

?> 

<HTML> 
<HEAD> 

<STYLE TYPE="text/css"> 

<!-- 

BODY, P {color: black; font-family: verdana; 

font-size: 10 pt) 

HI (color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 CELLPADDI NG=10 WIDTH=100%> 
<TR> 

<TD BGC0L0R="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=T0P WIDTH=83%> 
<Hl>Rate your boss anonymousl y</Hl> 
<?php echo Smessage; ?> 
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</TD> 
</TR> 
</TABLE> 

</B0DY> 
</HTML> 



Figure 17-2 shows the rating form after an error has occurred. 



FIGURE 17-2 



A multiple self-submitting form 



Morilla [Build ID: 2002051 Q06] HHE3 


. File Edit View Go Bookmarks Tools Window Help Debug QA 


(3^^ Gi (*J I *> httn^localhostfrate boss.php | [i^Seaich | |J/?/?| 


[ , My Yahoo! loMiuitejeunefillc ) , {Untitled) Q 


Rate your boss anonymously 




Something went wrong with your rating attempt. Try again. 




My boss is: 




r Driving me to look for a new job. 




C Not the worst, but pretty bad. 




f Just so-so. 




f Pretty good. 




r A pleasure to work with. 




Boss's name: [~ 




Submit | 




Document: Done 10.71 sees) ^K-hi* 



Some of you might be thinking, "Hey, wait! You said logic always comes before display — but then 
you started this script with a bunch of HTML." Very observant — but not quite right. Look closely, 
and you will realize that we are merely setting a bunch of text to a couple of variable strings ($ r e g_ 
form and $ rate_f orm). In the entire PHP section, we actually don't display anything. We merely 
construct a string, $message, which will be plugged in to the HTML at the bottom. If we took away 
the HTML, you would see a blank page in the browser. So it's okay to assemble the text you're going 
to want to display in the logic part; just don't echo it out to the browser until the end. 

Another issue with self-submitted forms is navigation. With the traditional HTML form, navigation 
is strictly one-way: form to handler to whatever navigational device (if any) the designer decrees. 
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Self-submitted forms need not conform to this rule, however. In each individual instance, you need 
to decide: 

■ Whether the form can be resubmitted multiple times by the user, in whole or in part 

■ Whether the user decides when to move on by clicking a link or the form moves users 
along automatically 

■ Whether you need to pass variables on to the next page, hidden or in plain view 

■ Whether you want to control where the user can go next or if you want to give users mul- 
tiple choices 

The answers to these questions will determine whether you need a control, another form, a simple 
link or button, or multiple links. 

ri f Whatever you decide about navigation, remember to provide plenty of text that clearly 

■ explains what's going to happen at every step. Because PHP gives you so much flexibil- 
ity with forms, new users' default expectations may be crossed up, and they could end up uncertain 
whether they accomplished their mission with your form. 



Editing Data with an HTML Form 

PHP is brilliant at putting variables into a database, but it really shines when taking data from a 
database, displaying it in a form to be edited, and then putting it back in the database. Its HTML- 
embeddedness, easy variable passing, and slick database connectivity are at their best in this kind 
of job. These techniques are extremely useful, because you will find a million occasions to edit data 
you're storing in a database. 

Let's look at the specific kinds of HTML FORM data elements and how they are handled. 



TEXT and TEXTAREA 

TEXT and TEXTAREA are the most straightforward types because they enjoy an unambiguous one- 
to-one relationship between identifier and content. In other words, there is only one possible VALUE 
per NAME. You just pull the data field from the database and display it in the form by referencing the 
appropriate array value, as shown in Figure 17-3. 

Listing 17-5, comment_edi t . php, takes a comment out of the database and allows you to edit it. 

You may need to use the stripslashes function when displaying TEXTAREA and TEXT 
if there's any chance the values might have single quotation marks or apostrophes. Watch 
out for people with apostrophe'd names like O'Malley or D'Nesh! 
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FIGURE 17-3 



Displaying text for editing 



Mniilla [Build ID: 2002051006] 



. File Edit View Go Bookmarks Tools Window Help Debug 0|A 

(^L | V htip^/lo c.i Ihost^co n^ment edh.pT~| |^Seaich"| 



Comment edit 

Your comment has been updated, 
jfte' men 10 not setting From- header correctly 



This is probably a sendmaii problem. Have you cried 
setting the fifth argument by hand? 



> I am setting the From: address in the mail header 

> by setting it in the first and fourth arguments to 

> maii() as it says in the PHP manual. But it's 

> still not working for me. Does anyone know why? 

> Thanks in advance, 
> 

> John 0- webdev 
Subinrt I 



f (0.83 sera} 



LISTING 17-5 



Editing data from database (comment_edit.php) 

<?php 

// Open connection to the database 
mysql_connect ( "1 ocal host" , "phpuser", "sesame") 
or die( "Fai 1 ure to communicate with database"); 
mysql_select_db("test"); 

if (isset($_P0ST['submit'] && $_P0ST[ ' submi t ' ] == 'Submit') { 
// Format the data 

$comment_id = mysql _real_escape_st ri ng ( $_P0ST[ ' comment_i d ' ] ) ; 
$comment_header = mysql_real„escape_stri ng( $_P0ST[ ' comment_header ' ] ) ; 
$as_comment_header = mysql _real_escape_st ri ng ( $comment_header ) ; 
Scomment = my sql_rea 1 _escape_stri ng ( $_P0ST[ ' comment ']) ; 
$as_comment = mysql_real_escape_stri ng ( $_P0ST[ ' comment ']) ; 

// Update values 
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Squery = "UPDATE comments 

SET comment_header = ' $as_comment_header ' , 
comment = ' $as_comment ' 
WHERE ID = $comment_id" ; 
Sresult = my sql _query ( $query ) ; 
if (mysql_affected_rows( ) == 1) ( 

$success_msg = '<P>Your comment has been updated . </P> ' ; 
) else ( 
error_l og(mysql_error()); 

$success_msg = ' <P>Somethi ng went wrong. </P>'; 

) 

I else ( 

// Get the comment header and comment 

$comment_id = my sql _real _escape„st r i ng ( $„GET[ ' comment_i d ' ] ) ; 
$query = "SELECT comment_header , comment 

FROM comments 

WHERE ID = $comment_id" ; 
Sresult = my sql _query ( Squery ) ; 
$comment_arr = mysql _f etch_a rray ( $ res ul t ) ; 
$comment_header = stri psl ashes ( $comment_arr[0] ) ; 
Scomment = stri psl ashes ( $comment_a rr[ 1 ]) ; 



Sthispage = "comment„edi t . php" ; //Have to do this for heredoc 

$form_page = <<< EOFORMPAGE 
<STYLE TYPE="text/css"> 

<!-- 

BODY, P {color: black; font-family: verdana; 

font-size: 10 pt) 

HI (color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 CELLPADDI NG=10 WIDTH=100%> 
<TR> 

<TD BGC0LOR="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=TOP WIDTH=83%> 
<Hl>Comment edit</Hl> 

$success_msg 

<F0RM METH0D="post" ACTI0N=" $thi spage " > 

<INPUT TYPE="text" SIZE="40" NAME="comment_header" 

VALUE="$comment_header"XBRXBR> 
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<TEXTAREA NAME="comment" R0WS=10 C0LS=50>$comment</TEXTAREA> 
<BRXBR> 

<I NPUT TYPE="hidden" NAME="comment_i d" VALUE="$comment_id"> 
<I NPUT TYPE=" submit" NAME=" submi t" VALUE="Submi t"> 
</F0RM> 

</TDX/TR></ TABLE) 

</B0DY> 

</HTML> 

EOFORMPAGE; 

echo $form_page; 

?> 



Remember that in an HTML form integers and doubles must use the TEXT or TEXTAREA 
type, as there is no specifically numeric HTML form field type. 

CHECKBOX 

The CHECKBOX type has only one possible value per input: off (unchecked) or on (checked). The 
database field that records this information is almost always going to be a small integer or bit type 
with values 0 and 1 corresponding to unchecked or checked check boxes. Figure f 7-4 shows a com- 
mon type of check box being edited. 

Listing 17-6 demonstrates how to use a check box to display and change a Boolean value. 



FIGURE 17-4 



A prepopulated check box 



Semi sleaiy opl-in form Mciilla (Build ID; 2002051006) 



_i_J 



„ Tile Edit View Go Bookmarks Tools Window Help Debug (JA 

O ^ | v hti p v/l a ca ihost'e d i i_ c li kb x .php | [C^Semch 1 fffij 



Your preference has been updated. 
Email address" jdevn u H@exomple.com 



Please send me lots of e-mail 
bulletins! 

Cijt fntf. by . b j' U .', rj- J; tany HnQ-X rtSC F 

Submit f 



Document: Done (0.72 5 
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LISTING 17-6 



Check box displaying boolean data from database (optout.php) 

<?php 

// Open connection to the database 
mysql _connect ( "1 ocal host" , "phpuser", "sesame") 
or di e( " Fai 1 ure to communicate with database"); 
mysql_select_db("test") ; 

// If the form has been submitted, record the preference and 
// redisplay 

if (isset($_POST['submit'] && $_P0ST[ 1 submi t ' ] == 'Submit') ( 
$email = $_P0ST[ 'email ' ] ; 

$as_email = mysql_real_escape_st ri ng ( $_P0ST[ ' ema i 1 ' ] ) ; 
if (isSet($_P0ST['0pt0ut'] && $_P0ST[ ' OptOut ' ] == 1) ( 

$optout = 1; 
) else ( 

$optout = 0; 

1 

// Update value 

$query = "UPDATE checkbox 

SET BoxValue = $optout 

WHERE BoxName = 'OptOut' 

AND email = ' $as_emai 1 ' " ; 
$result = my sql _query ( $query ) ; 
if ( mysql _e r ror ( ) == "") ( 

$success_msg = '<P>Your preference has been updated . </P> ' ; 
) else ( 
error_l og(mysql_error()); 

$success_msg = ' <P>Somethi ng went wrong. </P>'; 

1 

// Get the value 

$query = "SELECT BoxValue FROM checkbox 

WHERE BoxName = 'OptOut' AND email = ' $as_emai 1 ' " ; 
$result = my sql _query ( $query ) ; 
$optout = mysql_resul t( $resul t , 0, 0); 

if ($optout == 0) 1 

$checked = " " ; 
) elseif ($optout == 1) ( 
$checked = 'CHECKED' ; 

} 

} 



// Now display the page 

$thispage = "optout.php"; //Have to do this for heredoc 
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$form_page = <<< EOFORMPAGE 

<HTML> 

<HEAD> 

<TITLE>Semi -si eazy opt-in form</TITLE> 
</HEAD> 

<B0DY> 

$success_msg 

<F0RM METH0D=P0ST ACTI0N=" $thi spage " > 
Email address: 

<I NPUT TYPE="text" NAME="email" SI ZE=25 VALUE="$emai 1 "> 
<BRXBR> 

<F0NT SIZE=+4>P1 ease send me lots of e-mail bulletins! </ FONT) 
<BR> 

<F0NT SIZE=-2>opt out by clicking this tiny checkbox</FONT> 

<I NPUT TYPE="checkbox" NAME="0pt0ut" VALUE=1 $checkedXBRXBR> 

<I NPUT TYPE="submit" NAME=" submi t" VALUE="Submi t"> 

</F0RM> 

</B0DY> 
</HTML> 
EOFORMPAGE; 
echo $form_page; 

?> 



Although each check box is capable of expressing only a fixed chunk of data, check boxes are often used 
in bunches to convey more complex aggregate meanings. Look at the check box grouping in Figure 17-5. 

RADIO 

RAD 1 0 data elements allow for a one-to-many relationship between identifier and value. In other 
words, they have multiple possible values, but only one can be predisplayed or selected. They are 
best for small sets of options, generally between two and ten, which need more than a word or two 
of text to identify themselves. 

Unfortunately, it's somewhat more difficult to represent stored data in a radio button than in a check 
box or text field. This is because there is only one possible value for text or a textarea and only 
two possible values for a check box — but radio buttons can have more than two possible values. 
Therefore, you will have to output part of the actual form with PHP. This looks a little bit less neat 
than the styles we employed previously, so you have to go to a little more trouble to have an eas- 
ily readable script. Again, the user interface experience allowed by radio buttons is worth the extra 
trouble it gives to the web developer. 

In the example in Figure 17-6 and accompanying code, we are assembling a series of radio buttons 
that display preference data from the database. 
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FIGURE 17-5 



A cluster of check boxes 
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FIGURE 17-6 



Prepopulated radio buttons 
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Listing 17-7 shows the code for Figure 17-6, which shows how to edit forms with radio buttons. 



LISTING 17-7 



Radio buttons displaying boolean data from database (date_prefs.php) 

<?php 

// Subscriber ID is stored in a cookie on the user's browser 
if (isset($_COOKIE['userID'])) { 

$sub_id = my sql _real _escape_stri ng ( $_C00KI E[ ' user I D ' ] ) ; 

} 

if ( !isset($sub_id)) { 
die("Cookie Not Found."); 

} 

// Open connection to the database 
mysql_connect( "1 ocal host" , "mysql user" , "sesame") 
or die("Failure to communicate with database"); 
mysql_select_db("test"); 

// If the form has been submitted, record the preferences 

if (isset($_POST['submit'] && $_P0ST[ ' submi t ' ] == 'Submit') { 

$height = mysql _rea l_escape_stri ng ( $_P0ST[ ' hei ght ']) ; 

$haircolor = mysql _real_escape_st ri ng ( $_P0ST[ ' hai rcol or ']) ; 

$edu = mysql_real_escape_stri ng( $_P0ST[ ' edu ' ] ) ; 

// Update value 

$query = "UPDATE qualities 

SET height = $height, haircolor = $haircolor, 

edu = $edu 
WHERE subscriber = $sub_id"; 
$result = mysql_query ( $query ) ; 
if (mysql„affected_rows ( ) == 1) { 

$success_msg = '<P>Your preferences have been updated .</ P> ' ; 
I else ( 
error_l og(mysql_error()); 

$success_msg = ' <P>Somethi ng went wrong. </P>'; 

} 



// Get the values 

$query = "SELECT height, haircolor, edu FROM qualities 

WHERE subscriber = $sub_id"; 
$result = my sql _query ( $query ) ; 
$pref_arr = mysql_f etch_a r ray ( $ resul t ) ; 
$height = $pref_arr[0] ; 
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$haircolor = $pref_arr[l] ; 
$edu = $pref_arr[2] ; 



// Assemble the radio button part of the form 
if ($height == 1) { 

$radio_str .= "<INPUT TY PE=RAD 1 0 NAME=\ " hei ght\ " VALUE=1 
checked) Short<BR>\n" ; 
1 else { 

$radio_str .= "<INPUT T Y P E= RAD 1 0 NAME=\ " hei ght\ " VALUE=1> Short<BR>\n" ; 

} 

if ($height == 2) { 

$radio„str .= "<INPUT TY PE=RAD 1 0 NAME=\ " hei ght\ " VALUE=2 
checked) Average hei ght<BR>\n " ; 
I else ( 

$radio_str .= "<INPUT TYPE=RADIO NAME=\ " hei ght\ " VALUE=2> 
Average hei ght<BR>\n" ; 

} 

if ($height == 3) ( 

$radio_str .= "<INPUT T Y P E= RAD 1 0 NAME=\ " hei ght\ " VALUE=3 
checked) Tal 1 <BR)\n" ; 
I else ( 

$radio_str .= "<INPUT TY PE=RAD 1 0 NAME=\ " hei ght\ " VALUE=3> 
Tal 1 <BR>\n" ; 

} 

if ($height == 0) { 

$radio_str .= "<INPUT TYPE=RADIO NAME=\ " hei ght\ " VALUE=0 
checked) Doesn't matter<BRXBR)\n " ; 
I else ( 

$radio_str .= "<INPUT TY PE=RAD 1 0 NAME=\ " hei ght\ " VALUE=0> 
Doesn't matter<BRXBR>\n" ; 

) 



if ($haircolor == 1) { 

$radio_str .= "<INPUT TYPE 

checked) Bl onde<BR)\n " ; 

I else ( 

$radio_str .= "<INPUT TYPE 

Bl onde<BR)\n" ; 

} 

if (Shaircolor == 2) { 

$radio_str .= "<INPUT TYPE 

checked) Brunette<BR)\n" ; 

I else ( 

$radio_str .= "<INPUT TYPE 

Brunette<BR)\n" ; 

} 

if (Shaircolor == 3) { 

$radio_str .= "<INPUT TYPE 
checked) Redhead<BR)\n " ; 
1 else ( 



RADIO NAME=\"haircolor\" VALUE=1 

RADIO NAME=\ " hai rcol or\ " VALUE=1> 

RADIO NAME=\"haircolor\" VALUE=2 

RADIO NAME=\"haircolor\" VALUE=2> 

RADIO NAME=\"haircolor\" VALUE=3 
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$radio_str .= " < I N P U T TYPE=RADIO NAM E= \ " h a i rcol or\" VALUE=3> 
Redhead<BR>\n" ; 
} 

if (lhaircolor == 0) { 

$radio_str .= "<INPUT TYPE=RADI0 NAM E= \ " h a i rcol or\" VALUE=0 
checked> Doesn't matter<BRXBR>\n" ; 
) else { 

$radio_str .= " < I N P U T TYPE=RADI0 NAM E= \ " h a i rcol or\" VALUE=0> 
Doesn't matter<BRXBR>\n " ; 
) 

if ($edu == 1) 1 

$radio_str .= "<INPUT TYPE=RADI0 NAME=\"edu\" 
High school graduate<BR>\n"; 
) else { 

$radio_str .= " < I N P U T TYPE=RADI0 NAME=\ "edu\ " 
school graduate<BR>\n" ; 
} 

if ($edu == 2) 1 

$radio_str .= "<INPUT TYPE=RADI0 NAME=\"edu\" 
College graduate<BR>\n"; 
) else j 

$radio_str .= "<INPUT TYPE=RADI0 NAME=\ "edu\ " 
graduate<BR>\n" ; 
} 

if ($edu == 3) 1 

$radio_str .= "<INPUT TYPE=RADI0 NAME=\"edu\" 
Advanced degree hoi der<BR>\n" ; 
) else j 

$radio_str .= "<INPUT TYPE=RADI0 NAME=\"edu\" 
Advanced degree hoi der<BR>\n " ; 
} 

if ($edu == 0) { 

$radio_str .= "<INPUT TYPE=RADI0 NAME=\ "edu\ " 
Doesn't matter<BRXBR>\n " ; 
) else { 

$radio^str .= "<INPUT TYPE=RADI0 NAME=\"edu\" 
matter<BRXBR>\n" ; 
1 



// Now display the page 
$thispage = "date_prefs .php" ; //Have to do this for heredoc 

$form_page = <<< E0F0RMPAGE 

<HTML> 

<HEAD> 

<STYLE TYPE="text/css"> 
<! 

BODY, P (color: black; font-family: verdana; 



VALUE=1 checked) 
VALUE=1> High 

VALUE=2 checked) 
VALUE=2> College 

VALUE=3 checked) 
VALUE=3> 

VALUE=0 checked) 
VALUE=0> Doesn't 
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font-size: 10 pt) 

HI (color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 CELLPADDI NG=10 WIDTH=100%> 
<TR> 

<TD BGC0LOR="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=T0P WIDTH=83%> 

<Hl>Dating service</Hl> 

$success_msg 

<P>I am looking for a girl who is:</P> 
<F0RM METH0D=P0ST ACTI0N="$thi spage"> 
$radi o_str 

<INPUT TYPE=SUBMIT NAME=" submi t " VALUE="Submi t"> 
</F0RM> 

</TD> 

</TR> 

</TABLE> 

</B0DY> 

</HTML> 

E0F0RMPAGE; 

echo $form_page; 

?> 



SELECT 

The SELECT field type is perhaps the most interesting of all. It can handle the largest number of 
options, and it also allows the user to select multiple options that can be passed back to the database 
using arrays. 

c'ri r J'-" "rj'. rV See Chapter 39 for ideas about using JavaScript to make even more interesting SELECT 

LjlU^j.rr forms 

In Figure 17-7, we are using the SELECT form element with multiple options. In PHP, this is done by 
creating an array of the multiple selected option values to pass to the form handler. You set up the 
array in the HTML form by declaring the MULTIPLE attribute of the SELECT element and by naming 
the SELECT element something like $ v a 1 [ ] — in other words, appending a set of square brackets to 
the variable name. This will indicate to PHP that it's dealing with an array rather than a single vari- 
able, and it will construct the array appropriately with the multiple selected values. When the array 
gets to the form handler, you will need to deal with the values as you would any array's values — by 
dereferencing, or by listing out the contents of the array. 
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A prepopulated select with multiple choices 
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Listing 17-8 shows the code for Figure 17-7, which demonstrates how to display and edit a select list 
with multiple options. 



LISTING 17-8 



Select list displaying database values (skills_profile.php) 

<?php 

if (isset($_C00KIE[ ' userMd' ]) ) { 

$user_id = mysql _real_escape_st r i ng ( $_C00KI E[ ' user_i d ' ] ) ; 

} 



if ( ! i sset ( $user_i d ) ) I 
die("Cookie Not Found."); 

) 

// Open connection to the database 

my sql _connect ( "1 ocal host" , "mysqluser", "sesame") 

or die( "Database error!"); 

mysql_select_db("test"); 
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if (isset($_POST[ 'submit'] && $_P0ST[ 1 submi t ' ] == 'Submit') ( 

// Delete this user's skills 
$query2 = "DELETE FROM user„skill 

WHERE user_id = $user_id"; 
$result2 = mysql _query ( $query2 ) ; 

foreach ( $_P0ST ['skills'] as $val ) ( 

ScleanVal = mysql_real_escape_stri ng( $val ) ; 

$query = "INSERT INTO user_skill (ID, user_id, skill_id) 

VALUES (NULL, $user_id, ScleanVal)"; 
$ result = mysql _query ( $query ) ; 
if (mysql_affected_rows ( ) == 1) ( 

continue; 
} else ( 
error_l og(mysql_error()); 

$error_msg = ' <P>Somethi ng went wrong</P>'; 
break ; 




// Get all the results 

$query = "SELECT * FROM skills"; 

$result = mysql_query ( $query ) ; 

// Download this user's skills 
Squeryl = "SELECT ski 1 l_i d 

FROM user_skill 

WHERE user_id = $user_id"; 
$resultl = my sql_query ( $query 1 ) ; 

while ( $ u s e r_s kill = mysql _fetch_a rray ( $resul tl ) ) { 
$skill_id = $user_ski 1 1 [0] ; 
$user_ski 1 l_arr[$ski 1 l_i d] = $skill_id; 

} 



while (Sskills = mysql_fetch_array ( $resul t ) ) ( 
$key = $ski 1 1 s [03 ; 

if ($key == $user_ski 1 l_arr[$key] ) { 
$select_str .= "<OPTION VALU E=\ " $ key \ " 
SELECTED>$skills[l]\n"; 
) else ( 

$select„str .= "OPTION V A LU E= \ " $ key \ " > $ s k i 1 1 s[l]\n" ; 

} 

} 



$thispage = " s ki 1 1 s_prof i 1 e . php" ; //Have to do this for heredoc 
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$form_str = <<< EOFORMSTR 

<HTML> 

<HEAD> 

<STYLE TYPE="text/css"> 

<!-- 

BODY, P (color: black; font-family: verdana; 

font-size: 10 pt) 

HI {color: black; font-family: arial; font-size: 12 pt) 

--> 

</STYLE> 
</HEAD> 

<B0DY> 

<TABLE B0RDER=0 CELLPADDING=10 WIDTH=100%> 
<TR> 

<TD BGC0L0R="#F0F8FF" ALIGN=CENTER VALIGN=T0P WIDTH=17%> 
</TD> 

<TD BGC0L0R="#FFFFFF" ALIGN=LEFT VALIGN=T0P WIDTH=83%> 
<Hl>Skills profile</Hl> 

<P>Select as many skills from the following list as apply. Hold 
down the control key to select multiple skills. </P> 
$error_msg 

<F0RM METH0D=P0ST ACTI0N=" $thi spage " > 

<SELECT NAME=" s ki 1 1 s [ ] " SIZE=10 MULTIPLE> 

$sel ect_str 

</SELECT> 

<BRXBR> 

<I NPUT TYPE="submit" NAME=" submi t " VALUE="Submi t"> 
</F0RM> 

</TDX/TR></ TABLE) 
</B0DYX/HTML> 
EOFORMSTR; 
echo $form_str; 

?> 



Summary 

PHP is an extremely powerful form-handling tool, especially in conjunction with a database. You 
can use PHP to display database-stored data as form values, and of course, you can also store form- 
generated data in the database. 
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To prepare your HTML forms to work smoothly with PHP, you need to follow a few simple rules. 
First and foremost, never use data that comes from the user directly in a database call or query. This 
means using the my sql _real _escape_stri ng ( ) function on any $_P0ST, $_GET, and $_C00KI E 
values. Also, remember always to name every single form element — the HTML standard itself 
doesn't require this, but PHP does because the element names will become variable names in the 
form handler. One method that is sometimes helpful is to match the form element name to the cor- 
responding database field name so that they are easy to remember, perhaps prefixing form variables 
with f rm or something similar to help distinguish them from their database counterparts in code. 
PHP also allows you to make clever use of hidden form inputs and of multiple SELECT options, 
which should be delineated with square brackets (denoting an array) after the element name. 

You have the choice with PHP to have separate HTML forms and PHP form handlers or to combine 
the two in a PHP script. The latter option is arguably the more powerful, but it can also be more dif- 
ficult to work with and maintain. You will need to set a variable within the form to indicate whether 
the entries have been submitted; the PHP logic should be placed before the HTML display. You can 
even have multiple forms on one page that are handled by the same PHP script. 
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Improving Database 
Efficiency 



This quick chapter is for people making database-enabled PHP web 
sites who suspect that they are doing things awkwardly or inef- 
ficiently. Maybe you are new to databases, or maybe you know 
there must be a way to speed things up just because your pages are loading 
unacceptably slowly. 

We offer some tips and tricks for making things run faster, and we show 
you some common ways that database systems can save you from writ- 
ing unnecessary PHP code. As usual, some of our code examples will use 
MySQL functions, although the lessons are mostly general and independent 
of particular database implementations. 



This chapter will do little to help you get your database-enabled 
code working in the first place. For a guide to common errors, 
gotchas, and problems with PHP/database code, see Chapter 19. 



Connections — Reduce, 

Reuse, Recycle 

One important thing to realize is that establishing an initial connection 
with a database is never a cheap operation in terms of resource usage and 
time. Unless your PHP script is doing some unusually computationally 
intensive work, the overall database interaction will be the most time- and 
resource-intensive part of your code, and it is frequently true that the estab- 
lishment of a connection is the most expensive (in terms of resource usage) 
part of code that interacts with a database, even if the connection is only 
established once in serving the page. 



IN THIS CHAPTER 



Connections — reduce, reuse, 
recycle 

Indexing to speed up queries 
Make MySQL work for you 
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You have two potentially competing goals here. On one hand, you want to minimize the number 
of times your code makes the time-consuming call to open an entirely new database connection. 
This argues for leaving connections open during the course of page execution, rather than closing 
and reopening. On the other hand, there are sometimes hard limits on the number of simultane- 
ous connections that a database program can support. This might argue for closing connections 
whenever possible in hopes that less connected time per script might allow more scripts to execute 
simultaneously. 

In our experience, however, most web scripts are evanescent enough that it is never worth the over- 
head to close and reopen a database connection within one page's execution. If you want to mini- 
mize total time connected, open the connection immediately before the first call to the database, and 
close it immediately after the last one. 

A bad example: one connection per statement 

The first bad example seems stylistically reasonable in one sense because it uses a function to elimi- 
nate repetitive code. 

< ? p h p 

function box_query ($query, $user, $pass, $db) 
{ 

$my_connecti on = 

mysql_connect('localhost', $user, $pass) 

or die(" Couldn't connect to database"); 
mysql_sel ect_db( $db , $my_connecti on ) 

or die(" Couldn't select database"); 
$result_id = mysql_query ( $query , $my_connecti on ) 

or die(mysql_error()); 
pri nt ( " <H3>Res ul ts for query: $query</H3>" ) ; 
pri nt( "<TABLE>" ) ; 

while ($row = mysql_fetch_row( $resul t_i d ) ) 

{ 

print( "<TR>" ) ; 

$row_length = mysql_num_f i el ds ( $ resul t_i d ) ; 

for ($x = 0; $x < $row_length; $x++) 

( 

Sentry = $row[$x] ; 
print("<TD>$entry</TD>") ; 

} 

print("</TR>\n"); 

} 

print("</TABLE>") ; 

mysql_cl ose( $my_connecti on ) ; 

1 

/* code that uses box_query() */ 

?> 
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The idea is that we take a function that packages up an arbitrary MySQL query and displays the 
returned data in an attractive HTML table. The main virtue of this function as defined is that it is 
very self-contained — it opens its own database connection for its own purposes, and then it dis- 
poses of that connection when the function is done. 

The preceding code is fine if we expect to display only one such table per page. If we use this func- 
tion more than once per page, however, we will find ourselves opening and closing connections 
every time the function is invoked, which is bound to be less efficient than leaving the connection 
open. One approach is to leave a single connection open for as long as it is needed in the execution 
of a single page's script. Applying this rule to the preceding function would mean rewriting it so that 
it takes a connection as argument (or implicitly uses a connection opened at the beginning of the 
script) and then opening a single connection per page. 

Multiple results don't need multiple connections 

One thing that surprised us the very first time we saw web-database scripting was that, with many 
database programs, it is possible to retain the results from more than one query at one time, even 
though only one connection has been opened. For example, with a MySQL database you can do 
something like this: 

mysql_connect ( ' 1 ocal host ' , $user, $pass); //opens connection 
mysql_sel ect_db( 'scienceguide' ) ; 

$author_resul t = mysql_query( "SELECT ID FROM author") 

or di e(mysql_error( ) ) ; 
while ($author_row = my sql _f etch_row( $author_resul t ) ) 

( 

$book_result = 

mysql_query( "SELECT title FROM book 

WHERE authorlD = 1 $author_row[0] ) " ) 
or die(mysql_error()); 
while ($book_row = mysql _f etch_row( $book_resul t ) ) 
1 

$ti tl e = $book_row[0] ; 
print("$title<BR>"); 

1 

) 

This would print titles of books after retrieving them from the book table, using IDs from rows 
retrieved from the author table. If we assume there is not more than one author per book, then this 
is an extremely inefficient way to retrieve the data (see the section "Making the Database Work for 
You" later in this chapter), but it illustrates that two different result sets (identified by the variables 
$aut hor„resul t and $book_resul t) can be actively used at the same time, after having been 
retrieved over a single connection. 
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Persistent connections 

Finally, if you become convinced that the sheer overhead of opening new database connections 
is killing the performance of your application, you might want to investigate opening persistent 
connections. Unlike regular database connections, these connections are not automatically killed 
when your page exits (or even when mysql_close()is called) but are saved in a pool for future 
use. The first time one of your scripts opens such a connection, it is opened in the same resource- 
intensive way as with a regular database connection. The next script that executes, however, might 
get that very same connection in response to its request, which saves the cost of reopening a fresh 
connection. (The previous connection will be reused only if the parameters of the new request are 
identical.) 

rjj , "p~' I Persistent database connections work only in the module installation of PHP. If you ask 
— for a persistent connection in the CGI version, you will simply get a regular connection. 

The PHP function to request such a persistent connection for MySQL ismysql_pconnect( ), which 
is used in exactly the same way as mysql _connect ( ) . This naming convention seems to be stable 
across PHP functions for the different databases — if you use a particular DB connect function, you 
should consult the documentation to see if a pconnect version exists. 



Other than offering a particular kind of increased efficiency, persistent database connec- 
tions do not provide any functionality beyond that of regular database connections. In 
particular, you should not expect persistent connections to have any memory of previous queries or of 
variables from previous page executions. 



Indexing and Table Design 

MySQL is a pretty fast database, even absent any serious design considerations. In a lot of installa- 
tions and applications, the database-design part of your job maybe no more difficult than creating 
a single basic table with four or five fields in anticipation of holding no more than a few hundred 
records. However, as your database needs grow, your database itself will doubtless grow as well — 
in both size and complexity. That's no sweat for a good RDBMS: MySQL and other products in this 
class excel at handling these needs. Still, careful choice of both indexes and field types when design- 
ing tables can be crucial for performance as your tables get larger. 

Indexing 

Probably the first thing to investigate when SELECT statements are slow is whether you have defined 
appropriate indexes. 

What is an index? 

Wikipedia defines an index in the following manner: "A database index is a data structure that improves 
the speed of operations in a table" (http://en.wikipedia.org/wiki/Index_(database)). An 



282 



Improving Database Efficiency 



18 



index on a table field is an indication by a database designer to the database system that any searches 
made on that field should be fast. Usually, this is implemented by the RDBMS as a side table that 
maintains all the values for the field in order, and maps them to rows in the original table. Whenever a 
SELECT statement has a WHERE condition that mentions the indexed field, the side table is consulted to 
locate the rows that have the desired values for the field. The ordering of the side table means that the 
database system can do fast lookups (for example, using binary search). 

Indexing tradeoffs 

There are two mantras to keep in mind when thinking about creating indexes: 

■ S E LECT statements that filter on unindexed fields may require full table scans. 

■ While indexes speed up SELECT statements, they slow down I NSERTs, UPDATES, and 
DELETES. 

To see why both these statements are true, imagine that we gave you a large telephone book (sorted 
by last name) and asked you to find us everyone in the book with a first name of 'Zachary'. 
Unfortunately, it's difficult to see how to accomplish this without looking through the entire book. 

A database system trying to execute a statement like: 

SELECT lastname FROM phonebook WHERE firstname = 'Zachary' 

is in exactly the same situation, if there is no index on the field ' f i rstname ' . In database parlance, 
the system must resort to a full table scan, meaning that every row in the table is inspected. 

If your job were to do this phonebook lookup frequently, you might find it worth your while to com- 
mission an extra index (in the book-publishing sense) that listed all the first names in order, along 
with the page numbers and associated last names. Once the newly indexed phone book arrived, 
your job would become a lot easier. 

The bad news is that as soon as the new phone book arrived, we decided to promote you. 
Congratulations! Your new job is to keep the phone book up to date (including, of course, any asso- 
ciated indexes). Here is a list of 10,000 new customers, 8,000 people who have moved away, and 45 
people who have had name changes. Now the f i rstname index is a burden rather than a benefit. 
Again, it's the same with the database system — the indexes that make lookups faster are a mainte- 
nance burden when the data must be modified. 

The general lesson is that you should consider indexes on fields that you use frequently in the 
WHERE clauses of SELECT statements, especially when the data-modifying statements (INSERT, 
UPDATE, DELETE) will be used rarely. If modification is much more common than lookup, indexes 
make less sense. 

Now we move on to the specifics of using indexes in MySQL, beginning with the most common 
usage: a single index that uniquely identifies each table row. 



283 



Part II 



MySQL Database Integration 



Primary keys 

Simply put, a primary key is a field in a table that uniquely identifies each record in that table. A 
good primary key choice needs to meet a few criteria: 

■ A primary key should be of an integer type. These may vary some from one database tool 
to the next , but in My SQL , they are TINYINT, SMALLINT, MEDIUMINT, INT, and BIGINT. 
Refer to the MySQL online documentation for the current ranges and other properties of 
these types. 

■ A primary key should not return a null value. Your column definition should contain the 
SQL keyword NOT NULL. In fact, many databases, MySQL included, will not let you desig- 
nate a primary key that is capable of returning a null value. 

■ A primary key MUST be unique. That's the point, isn't it? And because a primary key must 
be unique, it should also have an auto -increment feature set. Most databases offer this, and 
most call it the same thing. 

r i ' Auto-increment and its use are often debated. In your Internet travels, you'll come across 

^ r -^ - those who don't like auto-increment and variously describe it as an accident waiting to 

happen or a cop out. To be honest, there are some meritorious arguments in this vein. However, we 
believe the benefits significantly outweigh the concerns. The alternatives are either expensive database 
calls to determine what key values are available or to generate an ID programmatically and then insert 
it with your SQL statement. Neither of these is as reliable nor worry free as auto-increment. 

If you've already forged ahead and created some database tables of your own without a primary key, 
consider the fields you have already created. Does one of these meet the tests described previously? 
It may be that you have wisely foreseen or intuited this need and created something like it already. If 
this field exists, but lacks one or more of the components, you can alter it with a SQL statement like 
the following: 

ALTER TABLE 'my_table' CHANGE ' exi sti ng_f i el d 1 'my_key' SMALLINT 
NOT NULL AUTO_INCREMENT PRIMARY KEY 

Or if your field already has all the necessary characteristics, you can simply make it the primary key 
like this: 

ALTER TABLE 'my_table' ADD PRIMARY KEY Cmy_key') 

In the first statement, we indicate that we are altering a table and indicate which table we want to 
operate on. CHANGE further indicates that we are changing a field's properties and indicating which 
field with its quoted existing name. We can then specify a name that may indicate more specifically 
what sort of field it is and set the relevant properties in one fell swoop. 

If you don't already have an appropriate field choice, the syntax doesn't change much: 

ALTER TABLE 'my_table' ADD 'my_key' SMALLINT NOT NULL 
AUT0_I NCREMENT PRIMARY KEY 
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Finally, you may just be creating your table for the first time. If that's the case, you simply need to 
include the following field definition in your table create statement: 

ID SMALLINT UNSIGNED AUTO_INREMENT NOT NULL PRIMARY KEY 

where ID is the name you've assigned to your primary key. There's nothing magical about this name; 
you can call it Fido if you want, but ID is a good, meaningful self-descriptive name. 

So now you've got a primary key. What's it good for? Well, it helps define the master record in a 
one-to-many relationship. Its other properties enforce an unambiguous identity for each record, 
such that the SQL statement delete from ' my_tabl e ' where id = 12 can have only one possible 
result. Phew, and you thought you just blew that whole table away. 

Creation of the primary key also has the net effect of speeding up queries that join tables on this 
unique ID because in the process of making it a primary key, we made it an index as well. An index 
is stored separately by MySQL and operates transparently to the end user. 

When you are defining a relationship in your SQL, the child table — the many side of the one-to- 
many relationship — will also store a copy of the master table's primary key value. But it will store 
it once for every record that is a child of the parent record, making it unsuitable for use as a primary 
key. You may still wish to define a primary key for each record in the child table — in fact, it's a 
good idea to do so, but you won't be able to define a primary key on this particular field because 
values may not be unique to this column. On the other hand, you still want to improve the process 
MySQL uses to locate related records for queries that perform joins. That works out alright, because 
MySQL can still index a field without making it a primary key: 

ALTER TABLE "child table' ADD INDEX Mylndex (child_id) 

This will work great for an existing field, but as before, you may need to create a suitable field for 
this purpose: 

ALTER TABLE ' chi 1 d_tabl e ' ADD 'child_id' SMALLINT NOT NULL 
Then make the field an index: 

ALTER TABLE 1 chi 1 d_tabl e ' ADD INDEX ( ' chi 1 d_i d ' ) 

Everything including the kitchen sink 

Indexes are almost a requirement for speedy, efficient joins. Even those most ardently concerned 
about things like disk space will rarely find room to argue about the merits of an index that speeds 
up the definition of relationships. More debatable, however, may be indexes that do not specifically 
operate on joins. 

You can index virtually anything. Sure, binary data presents some problems and is almost always 
an ill-advised choice for indexing, but strings, the larger text fields, and numbers (including floats 
and decimals) are all fair game. Aside from defining a relationship, the only other overriding 
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qualification for index candidacy is that it should be something you're likely to use in the WHERE 
clause of your SQL statement. 

Let's say you want to create a membership directory for your local Linux Users Group and you 
want members to be able to find other members in the same part of town so that they can easily get 
together for a drink or a movie. If you're like us, you're probably thinking Zip code. Excellent choice. 
A universally used (at least in the U.S.), well- documented, predictable and fairly stable search crite- 
rion. Of course, you don't have to index this field: 

SELECT name, phone from members where zip = '32223' 

will get you an answer, the same answer in fact, with or without an index. On a table with 100 or so 
records, you'll get your answer instantaneously — again, with or without an index. 

But maybe you have several hundred, perhaps even thousands of members. An index may just speed 
up this search. Add one and try your search again: 

ALTER TABLE 'members' ADD INDEX ('zip') 

Perhaps do it while watching the output of Linux's ps or top commands. Perhaps you'll see user 
discernible improvement; perhaps you'll need a professional diagnostic tool of some kind to measure 
what just happened; perhaps your performance improvement will be measured in nanoseconds. The 
point is, at some number of records, you almost certainly will see an improvement at each of these 
levels. It will be up to you as the designer to determine whether the benefits justify the tradeoffs. 

What are the tradeoffs? Disk space, for one. Depending on the number of records and the size of the 
field, an index can increase storage requirements by nearly as much as the table size itself. If you've 
got 80GBs of storage, you probably don't care. If you're on a 50MB shared hosting plan, you probably 
care very much. Another tradeoff is that although SELECT operations benefit, INSERT, UPDATE, and 
DELETE operations actually take longer because the indexes must be updated each time one of these 
is performed. The good thing about an index is that it's not irreversible. Try an index on anything 
you think might be useful, measure the performance improvement, and weigh it against what you 
may or may not be giving up to get that improvement. 

Other types of indexes 

There are a couple other types of indexes, or more appropriately, parameters to indexing functions, 
that specify how indexes work. Using them may have the net effect of making an index work better 
or worse. Again, consider each type, experiment and measure your results. It's a small effort to make 
with potentially huge dividends. 

UNIQUE 

Isn't that a primary key? Maybe. In MySQL at least, a primary key is by definition nothing more 
or less complicated than a UNIQUE INDEX with the name PRIMARY. If you find yourself defining a 
unique index, consider whether what you've got is really a primary key candidate. Social Security 
numbers, if your users are consistently willing to provide them, may work well in this regard. This 
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choice certainly meets the criteria and offers some additional advantages such as knowing what the 
primary key will be before you insert anything, enabling you to create master and child records 
without the intermediate call to mysql _i nsert_i d ( ) . 

A phone number, on the other hand, may not be such a good choice. Sure, it's unique. It also is, or 
can be defined as, an integer. But you may wish to store phone numbers as a string to avoid some 
post-formatting for creating a readable display, such as parenthesizing an area code or inserting 
the traditional, if somewhat meaningless hyphen. But even if you are willing to forgo the aesthetic 
concerns, as an integer, a phone number is almost certainly larger than necessary. The largest pos- 
sible phone number will store as 9,999,999,999. Yeah, that's what we said. This integer would 
require a field type of at least INT. You probably aren't going to store more than nine billion records. 
SMALLINTorMEDIUMINT would be better choices for a storage and searchable volume savings of 2 18 
or 2 9 bytes, respectively. 

All that said, you can still use UNIQUE without having it as a primary key, and that is precisely why 
it exists. A U N I QU E attribute on a phone number field can still serve as a data integrity check, once 
again relieving you of the responsibility of performing the check programmatically (of course, you 
will still probably have to respond to the problem). 

A unique index can be specified in MySQL like this: 

ALTER TABLE 'members' ADD UNIQUE my_index ('phone') 

Table design 

In Chapter 14, we discussed table design pretty extensively; we're not going to recap all that infor- 
mation here. However, we do want to reiterate some points about field types because choice of table 
fields can have significant performance impact. 

There are two interrelated concerns when choosing field types for a table: speed and size in memory. 
Your field definitions should anticipate the largest possible value that they may be asked to store, 
while not overanticipating and therefore creating unnecessarily huge tables with lots of unused 
space, both on disk and in memory. Appropriate field choices also come into play when choosing 
indexes for your table. Indexes are of the greatest benefit when they are set on a field type that is 
optimized for the type of data it is expected to hold. If, for example, you want an indexed number 
field where the count will never be more than 65,000 or so records, that index will perform more 
efficiently on the SMALLI NT field type than it will on the M E D I U M I N T field type, which allocates 
more space and therefore must search that extra space when attempting to isolate a specific value. 

A similar principle holds true for the string types. Although there's some debate whether or not it's 
even advisable to index on a string column, that index will certainly perform more efficiently on a 
field that is defined precisely to the specifications of the data you will wish to store on it. 

Earlier in this book, we pointed out that sometimes concerns about performance are so inflated that 
they border on the ridiculous. That's still the way we feel. It should not, however, appear inconsis- 
tent that we stress performance concerns now. This section and those that follow offer easily imple- 
mented design considerations that will collectively improve the performance of your databases. 
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Making the Database Work for You 

Just as when you write code in a programming language, writing code that interacts with a database 
is an exercise in appropriate division of labor. People who write programming languages and data- 
bases have agreed to automate, standardize, and optimize certain tasks that come up over and over 
again in programming, so that programmers don't have to constantly reinvent the wheel when mak- 
ing their individual applications. The very general rule is that, unless you're willing to spend a lot of 
energy in optimizing code for your special case, you are better off using a database-provided facility 
than trying to invent your own solution for the same task. 



It's probably faster than you are 



Database programs are judged partly on their speed, so database programmers devote a large por- 
tion of their effort toward ensuring that queries execute as quickly as possible. In particular, any 
searching or sorting of the contents of a database is best done within that database (if possible) 
rather than by your own code. 

A bad example: looping, not restricting 

For example, take the following code fragment (and please don't laugh — we have actually seen code 
like this): 

function pri nt_f i rst_name_bad ($lastname, $dbconnecti on ) 
{ 

$query = "SELECT firstname, lastname FROM author"; 
$ resulted = mysql_query($query, $dbconnection) 

or die(mysql_error()); 
while ($row = my sql _f etch_a rray ( $ resul t_i d ) ) 

{ 

if ( $row[ ' 1 astname ' ] == $lastname) 

print("The first name is " . $row[ ' f i rstname ' ] ) ; 

} 



When this code is handed a last name string and a database connection, it will print out associated 
first names, if any, in the "author table" of the database. For example, a call to pri nt_f i rst_ 
name_bad ( 'Sagan', Idbconnection) might produce the output: 

The first name is Carl 

If there were multiple authors in that table with the same last name, then multiple lines would be 
printed. 

The problem here is that we don't need to grab all the data in this table, pull it through the narrow 
pipe of a connection, and then pick and choose from it on our side of the pipe. Instead, we should 
restrict the query with a WHERE clause: 
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function pri nt_f i rst_name_better ($lastname, $dbconnecti on ) 
{ 

$query = "SELECT firstname, lastname FROM author 

WHERE lastname = ' $1 astname ' " ; 
$result_id = mysql^query ( Iquery , Idbconnecti on ) 

or di e(mysql_error( ) ) ; 
while ($row = mysql _f etch_a r ray ( $ resul t_i d ) ) 
{ 

print("The first name is " . $ row[ ' f i rstname ' ] ) ; 

} 

) 

The WHERE clause ensures that only the rows we care about are selected in the first place. Not only 
does this cut down on the data passed over the SQL connection, but the code used to locate the cor- 
rect rows on the database side is almost certainly quicker than your PHP code. 

Sorting and aggregating 

Exactly the same argument applies if you find yourself writing code to sort results that have been 
returned from your database, or to count, average, or otherwise aggregate those results. In general, 
the ORDER BY syntax in SQL will allow you to presort your retrieved rows by any prioritized list of 
columns in the query, and that sort will probably be more efficient than either homegrown code or 
the PHP array-sorting functions. Similarly, rather than looping through DB rows to count, sum, or 
average a value, investigate whether the syntax of your particular DB's flavor of SQL supports the 
GROUP BY construct and in-query functions such as count( ), sum( ), and average( ). In general, 
executing a query like: 

$query = "SELECT count(ID) FROM author"; 

will be a radically more efficient approach to counting table rows than selecting them and iterating 
through them with a PHP looping construct. 

Where possible, use M1N or MAX rather than sorting 

Although it's good to let the database system do your sorting for you, it's even better to not have to 
sort at all. One task that is often addressed by unnecessary sorting is finding the minimum or maxi- 
mum value in a set of result rows. You may see code like this: 

$query = "SELECT ID FROM author ORDER BY ID limit 1; 
// inefficient 

This query will return a single ID from the author table after having sorted it in ascending order 
— in other words, the minimum ID. It does have the virtue that the actual result set returned is 
small, so it is a better approach for finding the minimum than using the same query without the 
limit clause and picking off the desired value from the top of that large result set. But if all we are 
interested in is the minimum (or maximum) value, there is no need to require the DB to figure out 
the rank order of all the other IDs that we are not interested in. A better solution is: 

$query = select min(ID) from author; // efficient 
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The difference between these approaches will be imperceptible when your tables have only tens or 
hundreds of rows in them but will begin to matter as your tables grow to thousands or tens of thou- 
sands of rows in size. 

Creating date and time fields 

It is very common to want to associate a date and/or time with a row's worth of data. For instance, 
your table rows might represent requests made by your web site users, and the associated date/time 
is the time that that request hit your database. 

Now, one way to insert or update date fields is to include a string that represents the desired date in 
a format parsable by your database. For example, if you want to set the mydate datetime field of all 
rows of my t a b 1 e to a particular date, you might set up a query like this one: 

$query = "UPDATE mytable SET mydate = '2003-11-24'"; 

and then send that query off for evaluation. (Unfortunately, the exact standards of readable date for- 
mats vary quite widely from one SQL database system to another. This particular date string means 
November 24, 2003, as far as MySQL is concerned.) 

The preceding approach is fine, as long as you take care that the particular date string you send is, 
in fact, readable as a date by your DB. Things get more complicated if you need to construct such a 
string on the fly to represent a date that depends on the value of variables in your script. 

The main thing to remember is that, with most database systems, there is no need to go through 
such contortions to set a field to the current date or time. Many have a current-date function that 
can be embedded directly in your query. For example, a MySQL version of the preceding query that 
sets the relevant date/time field to the current instant looks like this: 

$query = "UPDATE mytable SET mydate = nowO"; 

Note that the call to now ( ) is not enclosed in single quotation marks, because it's a call to database 
function rather than a string to be interpreted by the database as data. The analogous query for 
Microsoft SQL Server looks like this: 

$query = "UPDATE mytable SET mydate = getdateO"; 

Finally, even if the time you want stored is not that of the instant of execution, there may still be 
better alternatives than constructing readable date strings in your script. In addition to functions 
returning the current date, many versions of SQL offer functions for performing date arithmetic — 
start with a particular date/time, and then add or subtract years, months, or hours. In MySQL, these 
functions are: 

■ d a t e_a dd(date, date- interval) 

■ date_sub(date , date-i nterval ) 



290 



Improving Database Efficiency 



Here date-i nterval is a string that includes a number of time units and the type of unit. A 
MySQL query to set all rows to a time a week from now might look like this: 

$query = "UPDATE mytable SET mydate = date_add(now( ) , INTERVAL 7 
DAY)" ; 

MySQL has a plethora of date and time related functions. See the MySQL documentation at: 
http://dev. my sql. com/doc/re fman/6.0/en/date-and-ti me -functions. html for more 
information on all of the functions. 

Finding the last inserted row 

Another surprisingly helpful capability offered by some database systems is finding the ID of the last 
row inserted. This problem arises when you are trying to create a new database entry that is distrib- 
uted across several database tables, each of which has an automatically incremented primary key. As 
an example, take the tables created by the following MySQL statements: 

CREATE TABLE author (ID int primary key auto_i ncrement , 
1 astname varchar(75) , 
firstname varchar (75)); 
CREATE TABLE book (ID int primary key auto„i ncrement , 
authorlD int, 
title varchar(lOO) ) ; 

One intent of these statements is that the book table is linked tothe author table by j oining them 
so that book.authorlD = author. ID. Another intent is that we don't have to worry about assign- 
ing unique ID fields for either table — the database will automatically assign them. Unfortunately, 
the combined intent leads to a problem. How do we write code that will gracefully insert a linked 
book-author pair, when both the author and the book are new to the database? If we insert a new 
author, the I D field of the inserted row will be automatically created by the database and so will not 
be a part of our SQL insert statement. How can we give the correct authorlD to our new book row? 

One possible strategy is to do something like the following (in MySQL): 

$author_l astname = 'Feynman'; 

$author_f i rstname = 'Richard'; 

$book_title = 'The Character of Physical Law'; 

$author_i nsert = "INSERT INTO author (lastname, firstname) 

VALUES ( ' $author_l astname ' , ' $author_f i rstname ')" ; 
my sql_query ( $a uthor_i nsert ) OR di e(mysql_error( ) ) ; 
$author_i d_query = 

"SELECT ID FROM author 
WHERE lastname = ' $author_l astname ' 
AND firstname = ' $author_fi rstname '" ; 
$author_id_resul t = 

my sql _query ( $author_i d_query ) OR die(mysql_error()); 
if (mysql_num_rows ( $author_i d_resul t ) <= 0) 
di e( " Inserted author not found!"); 
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else 

$author_row = my sql _f etch_row( $author_i d_resul t ) ; 
$authorID = $author_row[0] ; 

$book_insert = "INSERT INTO book (authorlD, title) 

VALUES ($authorID, $book_ti tl e) " ; 
mysql _query ( $book_i nsert ) OR di e(mysql_error( ) ) ; 

In this code, we create a new author row, use the last name and first name of the author to select the 
row we have just created, pull out the unique ID of that newly created row, and then incorporate 
that ID in a statement inserting a new row into the book table. This code would probably work in 
this particular instance, if we assume that the author's last name and first name are sufficient for 
unique identification. But for many databases, we will not be able to make such an assumption, 
which is, of course, why the convention of unique IDs developed in the first place. 

A similar approach that is sometimes used is to insert a row (for example, into the author table) 
and then select the maximum ID from that table, on the theory that the highest row ID will be the 
one most recently inserted. If the most recently inserted row is, in fact, the one we just inserted, 
this will work like a charm. Unfortunately, this is exactly the kind of approach that appears to work 
when tested by a solitary user/programmer and then breaks when used with a real database server 
that is dealing with requests from multiple connections at the same time. The problem is that an 
insertion from another connection might well arrive in between our own insertion and the statement 
we send to retrieve the maximum ID to date, with the result that our second insertion is matched 
with an inappropriate ID. 

The best solution, when it is available, is to have the database itself keep track of the last inserted ID 
in a retrievable way, and do this tracking on a per- connection basis, so that there are no worries about 
the synchronization issues in the previous paragraph. For MySQL users, PHP offers the function 
mysql_i nsert_i d ( ) , which takes a connection ID as argument and returns the auto-incremented 
ID of the last inserted row. We can use it to rewrite our previous code example: 

$author_J astname = 'Feynman'; 

$author„f i rstname = 'Richard'; 

$book_title = 'The Character of Physical Law'; 

$author_i nsert = "INSERT INTO author (lastname, firstname) 

VALUES ( $author_i nsert ) OR die(mysql_error( ) ) ; 
$authorID = mysql_i nsert_i d ( ) ; 

$book_insert = "INSERT INTO book (authorlD, title) 

VALUES ($authorID, ' $book_ti tl e ' ) " ; 
mysql _query ( $book_i nsert ) OR die (mysql_error( ) ) ; 

As with many PHP/MySQL functions, the connection argument to my s q 1 _i n s e r t_i d ( ) is actually 
optional and defaults to the most recently opened connection. 

In some other database systems, the ID of the most recent auto-increment is available (per session) 
as a "special" variable that can be embedded in the next query. In Microsoft SQL Server, for exam- 
ple, the variable is %%i denti ty, which can be embedded in a query as follows to retrieve the last 
insert ID: 

$query = "SELECT ©©identity"; 
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Summary 

Because database-related functionality is among the most resource-intensive things that PHP can do, 
you can become a hero by giving just a little thought to efficient coding practices. Particularly if your 
data-driven PHP scripts are sluggish, you want to learn to work with the database instead of against it. 

The basic principles of database-intensive coding are simple. It costs a lot to open a connection to a 
database, so don't turn the tap on and off unnecessarily. Remember the pipe is narrow — you want 
to transport the bare minimum of data you need for each page. And take the time to learn all the 
functionality your particular database can offer you. SQL is really good at indexing, sorting, filter- 
ing, restricting, numbering, and grouping — use these powers rather than doing it less well and 
more slowly with PHP. 

In Chapter 19, we move from these tips and stylistic concerns to problems and gotchas that can 
actually break your database code or give you unintended results. 
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MySQL Gotchas 



This chapter details some of the common difficulties that arise with 
using PHP and databases. The goal is to help you diagnose and 
solve problems more quickly and with less frustration. As usual, our 
specific code and function references are to MySQL (with one exception), 
although the set of gotchas is fairly independent across different databases. 



CjC/ ~£)--p ffp This chapter is about diagnosing and fixing PHP/database code 
~" ~ '■■ • that is genuinely broken — that is, it is not successfully retriev- 

ing data, or it is producing error messages. If your scripts are working, but too 
slowly, see Chapter 18. 



No Connection 



If you have a database call in your PHP script and the connection can't be 
opened, you will see a version of one of these two warning screens (depend- 
ing on how high your error reporting levels are cranked up, and, to some 
extent, the precise cause of the problem). 

The first possibility is the No Connection warning, as shown in 
Figure 19-1. 

This option indicates a problem either with the MySQL server itself or with 
the path to mysql d. In its own special way, PHP is telling you that it knows 
about MySQL but can't hook up to it. This is the error you will see on a 
working PHP-MySQL installation if the database server crashes. 

If the problem is on the PHP side, your error screen will look more like the 
one shown in Figure 19-2. 



IN THIS CHAPTER 



Connection errors 



Problems with privileges 
Unescaped quotation marks 
Bad SQL 

More or less data than expected 
Specific SQL functions 
Debugging 
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FIGURE 19-1 



A No Connection warning 
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FIGURE 19-2 



An undefined function fatal error 
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This means PHP doesn't know about MySQL at all. 

Of the two, the fatal error is much more straightforward to fix. Clearly, if you're running into an 
undefined function that is supposed to be in the PHP function set, you can be pretty sure that 
you simply forgot to build that module into your installation. So on the Unix side, you will need 
to recompile the code with the - -with-mysql option. On the Windows side, MySQL should be 
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precompiled into the binary for you and immediately available. In the case of any other supported 
database or a version of PHP older than 4.1, you merely need to uncomment the extens i on=php_ 
[database]. dll line in your php . i ni file to be ready to go, unless you put your MySQL execut- 
able in a very, very strange place (which you shouldn't do unless you're prepared to handle the 
consequences, including fatal errors). 

The innocuous-looking No Connection error is actually a little harder to diagnose because there are 
several possible causes. They fall into two main categories: 

■ The MySQL daemon isn't running. 

■ The MySQL socket isn't where PHP is looking for it. 

It's easy to check whether mysql d is running, so you may as well do that first. Just use whatever 
method you prefer to check running processes. On Windows, this means it's time for the old 
Ctrl+Alt+Delete action to bring up the Task Manager. On Linux you can check the system processes 
by means of p s . 

If mysql d is not running, perhaps you have merely forgotten to (re)start it. (Don't laugh. It happens.) 
If it's been running continuously for 143 days before suddenly quitting in the middle of an opera- 
tion, your problem is beyond the scope of this book. We can only direct you to the MySQL web site 
(at www .mysql .com) with our deepest sympathies and most fervent hopes that you've maintained a 
good backup schedule. 

The socket problem usually arises the first time you fire up MySQL on a new server. It's rather 
uncommon for this problem to occur in a long-running site, although it does happen. For instance, 
we recently had a web host move our MySQL daemon to another server on short notice, at which 
point all our scripts that used the hostname 1 oca 1 host immediately crashed. 

The solution to your database connection problems is generally to be found in the p h p . i n i file. 
There's a section of MySQL variables that you must carefully check against whatever hostname, port, 
and socket you're specifying in your PHP scripts. You want to ensure that you're not inadvertently 
directing PHP to look for MySQL on an odd port or at the wrong default host. On Linux, you can 
also check the / etc/services file for a different socket address, and the / etc/hosts file for an 
unexpected server alias. In general, you should leave these variables open unless you have a specific 
reason to set them. 



Problems with Privileges 

Error messages caused by privilege problems look a lot like the connection errors described previ- 
ously. You will see a No Connection error that looks like Figure 19-3. 

The key differentiator is that little piece about the user and password. 
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i r- 1 \ ^'t\h" Because of the security issues caused by these failure messages, which include the database 
WOi*^*^^*^ 1 username and host and whether you're using a password or not, it's best to use silent mode 
on a production site. You do this by putting the character @ in front of the functions mysql_connect 

and mysql__sel ect_db or by setting di spl ay_errors to off in the php . i ni file. 

These errors are many in number but fall into pretty clear major types: 

■ Employing a database username that lacks the necessary permissions for the task. 

■ Mistyping usernames/passwords. 

■ Failing to use a necessary password. 

■ Trying to use a nonexistent password. 

■ Trying to use your system's username/password instead of the MySQL username/password. 

■ Logging in from a location or client that the MySQL database does not allow for a 
particular user. 

■ PHP's being unable to open the database-password i ncl ude file because of incorrect file 
permissions. (It must be a file readable by your web.) 

■ The database root user's having deliberately changed permissions on you. 



FIGURE 19-3 
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These are not structural problems but usually just simple slips of memory that result in miscues or 
misrecollections. They are very common. We aren't too proud to confess that we've fallen victim to 
all of them — and not just once but over and over. They should be trivial to fix in the vast majority 
of situations. If you are confident your username and password combination is correct, you try using 
MySQL's FLUSH PRIVILEGES command to ensure that the most current changes are loaded. 
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Unescaped Quotes 

Quotes can cause many small but annoying buglets between PHP and MySQL. The crux of the issue 
is that PHP evaluates within double quotation marks and largely ignores single quotation marks, 
whereas MySQL evaluates within single quotation marks and largely ignores double quotation 
marks. This can lead to situations where you have to think hard about the purpose of each quotation 
mark. An example is: 

mysql_query( "INSERT INTO book (ID, title, year, ISBN) 

VALUES (NULL, ' $ t i 1 1 e ' , '$year', ' $ ISBN ' ) " ) ; 

In most of PHP, variables within single quotation marks are not expanded, whereas variables in dou- 
ble quotation marks or unquoted variables are — so this query looks a bit strange. But if you think 
about it, the statement is valid in both languages. The single quotation marks exist within double 
quotation marks, so PHP takes them as literal characters, and the variables are actually within 
double quotation marks, so PHP replaces them with their values. You can think of the division of 
labor this way: In a database query, PHP does its thing on the stuff between double quotation marks 
(treating single quotation marks literally), and MySQL later deals with the stuff left over within 
single quotation marks. 

Obviously, you'll need to exercise some care when writing these statements. This is one of the rea- 
sons why it's preferable to break up your MySQL queries into two parts, a query string and a my s q 1 _ 
query ( ) function, like this: 

$query = "INSERT INTO book (ID, title, year, ISBN) 

VALUES ( NU LL , ' $ t i 1 1 e ' , '$year', ' $ I SBN ' ) " ; 
$result = my sql _query ( $query ) ; 

This style also eliminates the double parentheses that account for common PHP errors. 

Even greater issues arise with strings that use single quotation marks and double quotation marks 
within the text. Remember that apostrophes and single quotation marks are the same thing for PHP 
and MySQL — they have no smart-quoting feature (not that most smart quotation marks are all that 
smart anyway). So this insertion query will break as follows if any of your lastname entries ever has 
an apostrophe in it (for example, O'Hara, D'Souza, and M'Naughten): 

$query = "INSERT INTO employee (ID, lastname, firstname) 

VALUES(NULL, 'llastname', ' $f i rstname 1 ) " ; 
$result = my sql _query ( $query ) ; 

Other very common problems are caused by names of businesses with apostrophes in them, such as 
Rosalita's Bar and Grill or Yoshi's Hair Salon, and by any string that might have a contraction or pos- 
sessive in it (such as can't, what's, or Mike's). 

The parallel issue on the PHP side is a string with a double quotation mark in it. This construction 
will definitely not work as intended: 

$string = "He said, "I'm not angry," but I knew he was."; 
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$statement = mysql_query ( " INSERT INTO diary (ID, entry) 

VALUES ( NU LL , '$string')"; 



9 I ver Y ' on 8 t ex t entries, a quotation mark problem may present as a partial string being 

" w " inserted, or it may appear as a complete failure, or it may seem as though only short 

entries are being accepted while longer entries fail. 

If you're using an HTML form with values, and only the first word of your string is being inserted, the prob- 
lem is likely to be that you forgot to quote the form value properly. In other words, your form field says 
< INPUT TYPE="text" VALU E=quoted string) rather than < I NPUT TYPE="text" VALUE="quoted 
s t r i n g " > . 

The following list reviews the three ways of dealing with quoting issues: 



■ In cases where the string is directly stated within the code, you can escape the necessary 
characters with a backslash. 

$query = "INSERT INTO employee (ID, lastname, firstname) 
VALUES ( NU LL , 'OVDonnell', 'Sean')"; 

■ In cases where the string is represented by a variable, you can use addslashes(), which 
will automatically add any necessary backslashes. 

$string = 

mysql_real_escape_stri ng( "He said, 'I'm not angry,' but I knew he 
was . " ) ; 

$statement = mysql_query( " INSERT INTO diary (ID, entry) 



For some murky psychological reason, many PHP users seem exceedingly averse to using a d d - 
s 1 a s h e s ( ) and its partner, stripslashes(). People will tie themselves in knots using single quo- 
tation marks when they really shouldn't, just so they don't have to escape double quotation marks. 
This practice is bad style at any time but is especially dangerous when using a database. 

You need to add slashes when inserting values into a database; conversely, you'll need to strip out the 
slashes when pulling strings from a database (unless you have magic quotation marks turned on). 

$query = "SELECT passphrase FROM userinfo 

WHERE username= ' $username ' " ; 
$result = mysql_query ( Iquery ) ; 
$query„row = mysql _f etch_a rray ( $ resul t ) ; 
$passphrase = stri psl ashes ( $query„row[0] ) ; 

If you fail to do this, more and more slashes will be added each time you reenter the data into 
MySQL! This is an issue that is very frequently encountered with editable Web forms that redisplay 
values pulled from a database, as shown in Figure 19-4. 

However, the preferred solution is to use mysql_real_escape_stri ng to escape characters prior 
to sending them to the database. 




VALUES (NULL, ' $stri ng ' ) " ) ; 
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FIGURE 19-4 
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Broken SQL Statements 

In addition to quoting problems, there are a number of easy ways to send a bad query to the data- 
base. That query might be syntactically malformed, have the right syntax but refer to tables that do 
not exist, or have any of a number of problems that make the database unable to handle it properly. 
A typical error message is shown in Figure 19-5. 



FIGURE 19-5 
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nB A MySQL error (such as the one shown in Figure 19-5) is different from a connection or 
™" link error, which looks something like Figure 19-1. A MySQL error is the error returned 
from the database when you try to do something that it doesn't like. It is not automatically echoed to 
the screen; you need to call mysql „error( ) to see any output. A connection error is a message that 
PHP is sending to you when an expected connection or link is not present. It is automatically echoed to 
the screen if you're using di spl ay_errors and must be silenced by being prepended with an @. 

Older versions of PHP used to automatically echo an error statement in these circumstances. Now, if 
you wish to find out what the problem is, you must manually call my s q I _e r r o r ( ) (as we've done in 
the preceding example) or my s q 1 _e r r n o ( ) . The safest way to capture these errors is to send them 
to a log file by using error_Jog( ). 

j.'j'r/f"? 7 "™ [ A broken or invalid SQL query is not the same thing as a query that returns no rows. You 
-J ; - can write a perfectly fine SQL query like the following: 

$query = "select ID from cust where name = 'nonexistent'"; 

You send it to your DB and get back a perfectly valid result set, which happens to contain exactly 0 
rows. Among other things, this means that error trapping that catches query failures will not help you 
detect the case of zero rows. For MySQLers, a helpful function is my sql n um rows ( ), which is called 
on the query result ID and returns an integer. 

Exactly how a bad SQL problem will present itself in your browser depends on your PHP version, 
your database version, your error settings, and how much error-checking code you have incorpo- 
rated in your script. Just as with other kinds of malignancy, early detection of a failed query is key. 

Your new best friend for making MySQL queries looks like this: 

$result = mysql_query ( $query ) or error_l og(mysql_error( ) ) ; 

Because my sql_query ( ) will return a false value if it fails, the er ror_l og ( ) portion will be 
executed only if a failure occurs. The low operator precedence of the o r operator ensures that the 
error_log() call also plays no role in the assignment statement — if the assignment succeeds, 
it is as if the e r r o r ( ) portion did not exist. Failure leads to the script exiting just as soon as it 
has printed the most informative error message that the MySQL designers could concoct. If your 
particular database lacks such an error variable in PHP, you might want to simply call e r r o r_ 
log($query). Often, the problem is obvious after you see the query that is actually being sent. 

If you have not incorporated error checking into your query calls, you will get the first bad news 
when you try to use the query result ID in subsequent database code. The typical pattern is: 

$my_result = mysql _query ( SbacLquery ) ; 

$row = mysql_f etch_row( $my_resul t ) ; // error shows up here 

The typical error message for MySQL isO is not a mysql result identifier in [some row]. 
This is because, rather than detecting the 0 value that my s q 1 _q u e ry ( ) returns when it fails, you 
have tried to use that value as if it were a valid identifier for a result set. 
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Although a bad query is by far the most common way of producing the 0 is not a 
valid result identifier message, it is not the only way. You would also get that 



message if you misspelled the name of the result identifier variable (and it was, therefore, unbound) or 
if the query statement had never actually executed (with the same result). Again, it is much easier to 
distinguish these problems if you trap the errors early on. 

If you suspect a broken query is causing your script to fail, liberal use of pri nt and va r_dump to 
output the actual SQL being executed is almost always helpful. I've found that seeing the SQL being 
executed will show a blatant error with quoting or an even subtler error. Taking the SQL and run- 
ning it manually through the MySQL CLI can also help to reveal errors. I will say more on this, later. 



Misspelled names 

The sad truth is that for every bug that plumbs the depths of programming esoterica, there are a 
gazillion cheap mistakes that seem obvious once you've discovered them. The former may break 
your brain, but afterward you feel a certain exhilaration at testing your skills against a really hard 
nut. The latter just leave you feeling empty and regretful at the time you wasted on something so 
trivial. 

So let us start with the single most common error: simple misspelling of table, column, and value 
names. It doesn't help that PHP and MySQL are both case-sensitive in Linux environments (but not 
on Windows). No force on earth can prevent you from using the wrong case once in a while, and the 
error messages will be uninformative at best. What can we say? Remember that even the most expe- 
rienced programmers do it, too. 



Comma faults 

Remember to put the comma outside the single quotation marks within a SQL statement. This will 
not work: 

$query = "UPDAf E book SEP ti tl e= ' $ti tl e , ' subti tl e= 1 Ssubti tl e , ' 
ISBN=' $ISBN ' " ; 

But this will: 

$query = "UPDAPE book SEP ti tl e= ' $ti tl e 1 , subti tl e= 1 Ssubti tl e ' , 
ISBN='$ISBN"'; 

Think of the single quotation marks as part of the variable itself rather than following common 
American typographical practice, which puts a comma inside the ending quotation mark. 



Unquoted string arguments 

Any values that should be treated by the database as string data types typically need to be single- 
quoted within a SQL statement. For example, this query has the correct syntax: 

$query = "SELECT * FROM author WHERE firstname = 'Daniel'"; 
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By contrast, if we make a mysql_query( ) call using the following query, we should expect an 
error: 

$query = "SELECT * FROM author WHERE firstname = Daniel"; 

The actual error returned by the database may be deceptive, though — quite likely the complaint 
will be about an unknown column named 'Daniel ' . This is because unquoted strings are assumed 
to name columns, as in: 

$query = "select * from author where firstname = lastname"; 

This would be a perfectly acceptable way to search our database for Humbert Humbert and Lisa 
Lisa, but it won't work for people with more ordinary names. 

Unbound variables 

One of the sneakier ways to break a SQL statement is to interpolate an unbound variable into the 
middle of it. 

When it works, the automatic splicing of variables into double-quoted strings is a perfect match for a 
SQL-based dialog with your database. Your code can determine values, for example, that are used to 
restrict the scope of a query made to the DB, as in this snippet: 

$customerID = f i nd_customer_i d ( ) ; //returns int 
$result_id = mysql_query( "SELECT * FROM customers 

WHERE ID = $customer_ID") ; //BUG 
$row = mysql__f etch_row( Sresul t_i d ) ; //CRASH 

Because this code makes no attempt to trap query errors, you will again see a complaint about the 
fact that 0 i s not a valid MySQL resul t i denti f i er. It's possible (for us anyway) to stare at 
code like this for quite a while without seeing anything wrong (although the good PHP coders who 
habitually crank error reporting up to E_A L L will be rewarded with the cause of the error in a warn- 
ing message). The problem, of course, is that we assigned one variable ($ customer I D) and then 
embedded a different one ($customer_I D) in our SQL statement. The latter variable is unbound 
and so behaves like an empty string when interpreted by the double-quote parsing. The result is that 
the database sees the following query, which is not valid SQL: 

SELECT * FROM customers WHERE ID = 



This kind of problem is one reason why it is often a good idea to construct your query and assign it 
to a variable in a separate statement, like this: 

$my_query = "SELECT * FROM customers WHERE ID = $customer_ID" ; 

Then make a distinct subsequent call to my s q 1 _q u e ry ( $ my_q u e ry ) . If you do this, it is very easy 
to add printing or logging statements that show you the actual query you are sending. 
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Too Little Data, Too Much Data 

Finally, you may find that your PHP/database script is working apparently without error but is dis- 
playing no data from the database or far more than you expected. As a vague and general rule, if 
your query function is returning successfully (and your code checks that), your suspicions might 
rightly turn to the SQL itself. Recheck the logic, particularly of WHERE clauses. It is easy, for exam- 
ple, to write a query like: 

"SELECT * FROM families WHERE kidcount = 1 AND kidcount = 2"; 

In this query, you are really intending an or rather than an and, with the result that zero rows will 
be returned regardless of the contents of your database. 

If your script is iterating through database rows and displaying them and you find that you have 
far, far too many of those rows, the problem is very often a SQL join that has too few restrictions. As 
a general rule, the number of restrictions in a WHERE clause should not be fewer than the number 
of tables joined minus one. For example, the following query has three tables but only one joining 
restriction: 

"SELECT book. title FROM book, author, country 
WHERE author . country ID = country. ID" 

It is likely to return every possible book/author pair, without reference to whether the author wrote 
the book, which is probably not what was intended. 



Specific SQL Functions 

A few specific functions seem to cause a higher than normal number of problems, especially in the 
learning phase. These functions can send even the experienced PHP developer running to the online 
manual to check the arguments and returned data types time and time again. 

mysql_affected_rows() versus mysql_num_rows() 

Both of these functions tell you how many rows of data your last SQL statement touched. However, 
mysql_num_rows ( ) works only on SELECT statements, while mysql_af f ected_rows ( ) works 
only on INSERT, UPDATE, and DELETE statements. The way to think about it is that SELECTs do not 
affect (meaning change) any data that exists in the database. 

Furthermore, mysql_af f ected_rows ( ) takes an optional link identifier as the argument, whereas 
mysql _num_rows ( ) takes a nonoptional result resource. This means that you can only get a valid 
result from mysql_affected_rows( ) until the moment you call another INSERT, UPDATE, or 
DELETE. In contrast, if you use different variable names for your result resources, you can use 
mysql_num_rows ( ) anytime in the script. This code will help clarify the differences: 

$link_id = mysql_connect($host, $user, $pass); 
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mysql _sel ect_db ( Sdatabase, $1 in k_i d ) ; 

$query = "INSERT INTO mytable VALUES ( NU LL , '$myval')"; 
$resul t_resource = my sql_query ( $query ) ; 
$test_insert = mysql_af f ected_rows ( ) ; 
// This should work and neturn 1 

$queryl = "SELECT * FROM mytable"; 
$resul t_resourcel = mysql_query ( $queryl ) ; 
$test_select = mysql_num_rows($resul t_nesourcel ) ; 

$query2 = "DELETE FROM mytable"; 
$resul t_nesource2 = my sql _query ( $query2 ) ; 
$test_sel ect2 = my sql _num_rows ( $ resul t_resource2 ) ; 
//Wi 1 1 not work 

$test_delete = mysql_af f ected_rows ( ) ; 

//This will return the number of rows in the table; at this 
// point you can no longer get the old result of 1 
$test_sel ect_aga i n = mysql_num„rows ( $resul t_resourcel ) ; 
//Should be the same as $test_select 

mysql_result() 

This function, which returns one value at a time from the database, is now used rather rarely. Unlike 
mysql _fetch_row( ) and mysql _f etc h_a r ray ( ) , with mysql _resul t you need to specify the 
row and field of the value you're fetching as well as the result resource. Thus, you cannot do this: 

// This won't work 

while (my sql_resul t ($ resul t_resource ) ) I 
// Some loop 

} 

// This wil 1 

$firstname = mysql_resul t( Sresul t_resourcel , 0, ' f i rstname ' ) ; 

You should really use this function only when you know you'll be fetching one or two pieces of data 
(a user's first name, for instance). Otherwise, the others are much faster. 

OCI_Fetch() 

When users of MySQL or SQL Server switch over to Oracle, they often have trouble with the OCI 
fetching functions — particularly this one. Unlike most other database row-fetching functions, you 
don't immediately access the result of oci_f etch ( ) via echo or some other PHP function. This 
function fetches the result of a SQL statement into a result buffer — where it can be accessed via 
OCIResultO. 

$query = "SELECT * from mytable"; 
$ stint = oci„parse( $conn , $query); 
$exec_result = oci_execute( $stmt , 0 C I_D E FAU LT ) ; 
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$row2buffer = oci_f etch ( $ strut ) ; 

$myval = oci_resul t( $stmt , "MYCOLUMN"); 

echo $myval ; 

This function should probably be thought of as analogous tomysql_result() rather than my s q 1 
f etch_row( ) , or at best occupying a middle ground between the two. Similarly, it should only 
be used when you are sure you will be fetching very small data sets. Otherwise, use oci_f etch_ 
a rray ( ) which returns an array. 



Debugging and Sanity Checking 

If you are nearing your wit's end in trying to debug query-related errors and misbehavior, you may 
find it extremely useful to compare the results of your PHP-embedded queries with the same queries 
made directly to the database. If your technical setup permits actually running a SQL client directly 
(for example, the mysql or Oracle command-line clients), as well as cross-program cutting and past- 
ing, try this two-step process: 

1 . Insert a debugging statement in your PHP script that prints the query itself immediately 
before it is actually used in a DB query call (for example, echo $query). 

2. Directly paste that query from your browser output (or the HTML source) into your 
SQL client. 



CAUTION 



Obviously, this advice applies only to code under development, not to code you are run- 
ning in production. It might be okay to echo errors to the browser while you're develop- 
ing something for the first time, but when it's ready to go into production, you should make sure all 
your e c h o ( ) statements are replaced with e r r o r_l o g ( ) functions. 



If the query looks reasonable to you, but it breaks both in the SQL program and in PHP, then there 
is some syntax or naming error in that SQL statement itself that you are missing, and your PHP code 
is not to blame (unless, of course, your code constructed that query in the first place). Similarly, with 
a dearth or overabundance of rows — if the behavior is the same in both places — the query is to 
blame. If, on the other hand, the behavior in the SQL interpreter looks like what you wanted, then 
the query is fine, and your suspicion should turn to your PHP code that actually sends that query 
and processes the results. 

One final and general tip is to study any error messages very carefully, paying attention to phrases 
like link identifier and result resource identifier. In MySQL, the former means an iden- 
tifier of a database connection, and the latter identifies the set of rows returned by a particular query. 
It is easy to confuse the two, as in the following code: 

$my_connecti on = mysql_connect( ' 1 ocal host ' , $myname, $mypass); 
mysql„sel ect_db( ' MyDB ' ) ; 

$result = mysql_query ( $my_query , $my_connecti on ) ; 
while ($row = mysql_fetch_row( $my_connecti on ) ) ( 
// LOOP 
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This code will probably yield an error that contains the words not a valid result identifier. 
The problem is that we are using the connection ID where the result ID should be. The resulting 
error message is justified yet opaque. 



Summary 

PHP/database bugs are often not very deep or subtle but can still be difficult to diagnose. In general, 
the earlier in a script you can detect trouble, the easier the diagnosis will be. Especially when you 
are debugging, every statement that interacts with the database should have an associated error_ 
1 og ( ) clause, containing an informative error message. 

By far, the most common cause of database-connection problems is incorrect arguments to the con- 
nection function (hostname, username, password). The most common causes of failed queries are 
quote faults, unbound variables, and simple misspellings. 

If you have repeated failures with database queries that seem like they should be working, have your 
code print out the query that it is sending to the DB; if possible, try making that very query to the 
database directly. If the problem persists when PHP is out of the loop, you can safely restrict your 
attention to database design and your understanding of SQL queries. 
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Introducing Object-Oriented 



PHP 



There are many possible audiences for this chapter, including people 
who know basic PHP but nothing about object-oriented program- 
ming (OOP), and people who know all about OOP and nothing 
about PHP. As usual, we aim to please everyone all at once, but be warned 
that you may want to pick and choose from the sections. 

We start with a quick and very general introduction to object-oriented 
programming for those who are completely unfamiliar with it. If you are 
already comfortable with OOP from another language, please skip this 
section — it will not enlighten you (and might well enrage you). The sec- 
tion "PHP Constructs for OOP" gets into the meat of the basic syntax and 
behavior of PHP objects. Later in the chapter, we delve into more extended 
examples and cover some of the more obscure issues and gotchas around 
objects in PHP. Along the way, we offer a couple of sidebar meta-discus- 
sions, about the merits of object-oriented PHP and the extent to which PHP 
should be considered to be OOP. 



NOTE 



In general in this chapter, we discuss OOP programming con- 
structs as they are implemented in PHP5, which uses the new 
and significantly improved Zend Engine 2 as its parser. 



IN THIS CHAPTER 



What is object-oriented 
programming? 

The basics of PHP OOP 

Advanced topics: serialization 
and introspection 

Troubleshooting and style issues 



311 



Part III 



More PHP 



What Is Object-Oriented 

Programming? 

So what is object-oriented programming (OOP) all about anyway? OOP turns out to be a very simple 
idea, which (when taken seriously and built into the structure of programming languages) leads to 
all sorts of more complicated elaborations. 

The simple idea 

The simple idea is this: Rather than creating data structures on the one hand and code on the other, 
suppose that we reorganize everything so that associated pieces of code and data are bundled together? 

The procedural approach 

For example, imagine a conventional procedural (non-object-oriented) program for manipulating per- 
sonal calendars, with the capability to display, update, and edit calendars. Somewhere in the code for 
such a program, we would find the actual data definitions for representing someone's appointments 
for a particular month; somewhere else we would find code that did the right things to manipulate 
that data. Typically, the only connection between the data type definitions and the manipulation code 
is that a clever programmer has made sure that they get matched up appropriately. 

Now imagine combining our calendar program with a recipe program (say that we want to plan our 
meals in detail for an entire year). Again, there will be data structures somewhere that represent the 
contents of the calendar, and other data structures that represent the contents of the recipes. The 
data structures will use the basic data types of the programming language; for all we know, the top- 
level type of a calendar might be an array, and the top-level type of a recipe might also be an array. 
Somewhere else in the program there is code for digging into the data structures that represent cal- 
endars and recipes and doing the right things with them. What is the connection between the data 
structures and the code? Only that a careful programmer has made sure that the arrays that repre- 
sent calendars and the arrays that represent recipes get fed to the appropriate manipulation code. 
(Otherwise, we might find ourselves trying to schedule an appointment in Beef Stroganoff rather 
than in March 2006.) 

If we think of procedural code as outlined like a book, the outline for the code we're talking about 
might look like: 

■ Data definitions 

Data definitions for calendars 
Data definitions for recipes 

■ Data manipulation code 

Code for calendars 
Code for recipes 
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The object-oriented approach 

The most basic version of OOP reorganizes the procedural approach by grouping associated pieces 
of code and data together into conceptual units. This means that we replace the outline in the pre- 
ceding subsection with: 

■ Calendars 

Data definitions 
Manipulation code 

■ Recipes 

Data definitions 
Manipulation code 

This organizational inversion is the heart of object-oriented programming. 

But so what (we can hear you say)? If we're just talking about a way to organize code, we could do 
that without any special terminology or programming languages. In normal procedural code, we 
can organize function definitions and data type definitions in any order we want to. For example, 
we could put all the data type definition code into one directory and all the manipulation code into 
another (a procedural organization), or we could put all the calendar code into one directory and all 
the recipe code into another (an object-oriented organization). 

Object-oriented programming begins to be interestingly different from procedural programming, 
however, once the programming language itself is set up to make it easy to organize things in an 
object-oriented way. (See the sidebar "Do Web-Scripting Languages Really Need OOP?" for a dis- 
cussion of how useful this organization is in languages like PHP.) The most basic form this takes is 
that data objects can be built out of local functions as well as local data. For example, as we build a 
data structure that represents a calendar, we can include the data members that are needed (struc- 
tures to represent days, months, years, appointments) but also the functions that will be needed 
(new_appoi ntment ( ) , cal en da r_di spl ay ( ) , and so forth). These functions are (in some sense) 
stored locally in the object definition itself. A calendar doesn't have an ingredient list, and a recipe 
doesn't have 31 days; similarly, a calendar object doesn't have a pri nt_i ngredients( ) function, 
and a recipe doesn't have a new_appoi ntment ( ) function. Finally, of course, the data members in 
an object may themselves be objects of a different type. 

Bundling code and data together into units is the basic idea, and OOP languages always offer some 
support for this kind of bundling. However, most OOP languages take things further and offer one 
or more of the following elaborations that give OOP even more leverage. (See the sidebar "How OO 
Is PHP?" for a discussion of the extent to which PHP itself has these features.) 

Elaboration: objects as data types 

In addition to allowing us to store functions in our data, a good OO programming language lets us 
define these combinations as genuinely new data types that the language supports like any other type. 
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Do Web-Scripting Languages Really Need OOP? 

The object-oriented revolution has not been without controversy. Although many programmers embraced 
OOP quickly, others preferred the procedural approach they were used to and wondered aloud if the 
extra machinery needed to support OOP wasn't more trouble than it was worth. Still, there's no doubt that 
the revolution has largely succeeded. Most of the popular programming languages in use today are either 
fully object oriented or have object-oriented extensions. Also, at least some of the promises about improved 
productivity and increased code reuse seem to have been realized, as design methodologies like the Unified 
Modeling Language (UML) and patterns gain greater influence, and as people get more used to subclassing as 
a standard way to reuse and extend vendor-supplied libraries. 

We feel that the benefits of OOP for "major" (that is, compiled) programming languages like Java and C++ are 
clear. On the other hand, we feel that the benefits of OOP for scripting languages (like Perl and PHP) are less 
obvious and are most debatable in the case of web-scripting (PHP). 

How is web scripting different from other kinds of programming tasks? The most obvious difference is simply 
that web scripts typically execute quickly and then go away. In other programming situations, you may have 
RAM-resident objects that live for hours or days and undergo complex evolutions of state that affect their 
behavior. A typical web script, on the other hand, might execute for half a second, as it serves up a particular 
page, and then dies happy. You may knit these scripts together to provide a more extended user experience 
(using databases, sessions, cookies), but often such efforts are all about making the experience outlive any 
PHP objects that may be created. More generally, scripting languages like PHP and Perl typically have a less 
thoroughgoing implementation of OOP than languages like Java, C++, and Smalltalk, and the limitations of 
implementation make these OOP extensions less attractive. (For more detail, see the sidebar "How OO is 
PHP?" later in this chapter.) 

This is not to say that there aren't still benefits of OOP in PHP. In addition to the conceptual benefits that may 
result from structuring code in an object-centered way, there are two good reasons to use PHP objects: 1) It's 
a good way to distribute third-party code for reuse; 2) Many programmers who are used to OO syntax from 
other languages won't feel comfortable unless they can use the same idioms in PHP. 

But our main point is that use of PHP constructs for OOP is a very "tradeoffy" and pragmatic decision, which 
we have often seen made more on the basis of religion or fashion. If you are comfy with OO, this kind of 
syntax is there for you, and if you work in a group that has decided to write in that style, you may want to let 
the majority rule. If you decide not to go OO, however, be strong — we urge you not to be swayed by the 
moral-superiority arguments you may hear from people who disdain your five-line procedural script in favor 
of their ten-line OO script that does exactly the same task. 



After such a type is defined, we can create as many such objects as we like, just as we can create as 
many integers as we like given the integer type. In object-oriented terminology, the term class is used 
to refer to the general type definition, which specifies the data members and member functions that 
each instance of that class should have. 

The term object (or instance) refers to any individual instance of the type. For example, after we 
define a class called Calendar (which specifies the different kinds of data and functions that every 
self-respecting calendar should have), we can make any number of Calendar objects (which might 
be associated with individual people). 
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Elaboration: Inheritance 

After we've written a program that uses the class Calendar, we might want to make a more specific 
version of the program for a particular purpose. What we would really like to do is copy most of the 
code from the Calendar class but change it in just a few places, so that it prints differently or has 
a culturally appropriate set of holidays or allows us to schedule appointments to the second rather 
than to the hour. 

This desire is common enough that OOP offers a mechanism to support it called inheritance. The 
basic idea is that you can define a class in terms of another class and then specify only the things 
that you want to be different in your own class. If you view the original class as the parent, the 
default is that both function definitions and data definitions are inherited by your child class unless 
you specify otherwise. This turns out to be a powerful technique for reusing class definitions. (As 
you will see in the "Basic PHP Constructs for OOP" section, OOP in PHP supports inheritance.) 

Elaboration: Encapsulation 

Part of the point of segregating both data and functions into objects is to reduce the complexity 
of programming by reducing unnecessary interactions. There is no reason why calendars should 
have to know about the internals of cooking recipes, or vice versa. So some OOP languages actu- 
ally enforce information barriers between objects — after the programmer has defined which parts 
of recipes and calendars are purely internal and private to those classes, the language actually for- 
bids code that is external to an object from messing with an object's internal workings. This kind 
of information-hiding is called encapsulation, and although this sounds restrictive, it can be a good 
source of clarity. In particular, if the programmer who designed a particular class knows that some 
parts of its workings have been designed to be private in this sense, the programmer also knows that 
those parts can be redesigned without checking with everyone who might be using that class's code. 
Support for encapsulation existed for the first time in PHP5, which incorporates Zend Engine 2. 
You'll see how to use encapsulation later in this chapter. 

Elaboration: Constructors and destructors 

After you have defined a class, you can make as many instances of it as you like. Each time you cre- 
ate such an instance, your favorite OOP language allocates memory to store the instance in, and 
gives you some way to refer to that instance later in the program. There are frequently a number of 
initialization steps you want to take every time you make an object of that class. Constructor func- 
tions offer a way to build that set of steps into the class definition. The standard way to create a new 
instance is to call a constructor function (which usually has the same name as the class and which 
you can customize to do all the necessary initialization). 

Destructors are the opposite of constructors and specify all the cleanup actions that should happen 
when an object is dispensed with. 

PHP has offered constructor functions since version 4.2 (which makes sense, because you can't have 
object orientation without having constructors). The language acquired explicitly definable and call- 
able destructors only in PHP5 (destruction of classes was handled only in an automatic way before 
then). Again, these functions are covered later in this chapter. 
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Terminology 

There are some standard terms in OOP parlance for all the concepts we have talked about thus far, 
and we will be using them for the rest of the chapter. (Several of these terms have alternate names, 
which we include in parentheses.) 

■ Class: This is a programmer- defined data type, which includes local functions as well 
as local data. You can think of a class as a template (or mold, or form) for making many 
instances of the same kind (or class) of object. 

■ Object: (Also known as object instance, or instance) An individual instance of the data 
structure defined by a class. You define a class once and then make many objects that 
belong to it. 

■ Member variable: (Also known as property, attribute, or instance variable) One of the com- 
ponent pieces of data in a class definition. 

■ Member function: (Also known as method) A member that happens to be a function. 

■ Inheritance: The process of defining a class in terms of another class. The new (child) 
class has all the member data and member function definitions from the old (parent) class 
by default but may define new members or "override" parent functions and give them new 
definitions. We say that class A inherits from class B if class A is defined in terms of class B 
in this way. 

■ Parent class (or superclass or base class): A class that is inherited from by another class. 

■ Child class (or subclass or derived class): A class that inherits from another class. 



How OO is PHP? 

How "object-oriented" is PHP? Your answer to that question probably depends on your particular litmus 
tests for object-orientedness. In this sidebar, we offer a whirlwind tour of features that typically show up in 
OOP languages and briefly discuss the extent to which PHP supports them. Some of these issues are explored 
more broadly in the section "Advanced OOP Features," later in this chapter. (Note: This sidebar is really only 
of interest to developers who are coming to PHP from a different OO language; everyone else may want to 
skip this game of buzzword bingo.) 

Sin gle inheritance 

PHP allows a class definition to inherit from another class, using the extends clause. Both member variables 
and member functions are inherited. 



Multiple inheritance 

PHP offers no support for multiple inheritance as in Java. Each class inherits from, at most, one parent class 
(though a class may implement many interfaces). 
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Constructors 

Every class can have one constructor function, which in PHP is called cons t r uct ( ) . Note that there are 

two underscore characters at the front of that function name. Because prior to PHP5 (under Zend Engine 1), 
a class's constructor function had the same name as the class, PHP still allows (but discourages) that strategy 
for purposes of backward compatibility. Constructors of parent classes are not automatically called but must 
be invoked explicitly. 

Destructors 

PHP supports explicit destructor functions as of version 5. The destructor function of a class is always called 

destruct( ). 

Encapsulation/access control 

PHP supports public, private, and protected variables and member functions as of version 5. 

Polymorphism/overloading 

PHP supports polymorphism in the sense of allowing instance of subclasses to be used in place of parent 
instances. The correct member function will be dispatched to at runtime. There is no support for method 
overloading, where dispatch happens based on the method's signature — each class only has one member 
function of a given name. However, PHP's weak typing and support for variable numbers of arguments makes 
workarounds possible. See the section "Simulating polymorphism" later in this chapter (in the section "Advanced 
OOP Features"). 

Early versus late binding 

Two equally good answers are: (1 ) The question doesn't arise, because of PHP being loosely typed, and (2) All 
binding is late. In PHP, values are typed but variables are not, so there is no question about what method to 
call when the variable is of a different type than the value. 

Static (or class) functions 

PHP offers static member variables and static methods as of version 5. It is also possible to call member func- 
tions via the CI assname : : f uncti on ( ) syntax. 

Introspection 

PHP offers a wide variety of functions here, including the capability to recover class names, member function 
names, and member variable names from an instance. (See the section "Introspection Functions," later in this 
chapter.) 

Namespaces 

PHP6 offers namespaces; these define the area in which an identifier, such as a variable, is unique. For example, 
a variable named $f oo inside of a private namespace is different from a global variable $f oo. 
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In this section, we cover the basic PHP syntax for OOP from the ground up, with some simple 
examples. 

Defining classes 

The general form for defining a new class in PHP is as follows: 

class myclass extends myparent 1 
public $ v a r 1 ; 

public $var2 = "constant string"; 
public function my tunc ( $ a r g 1 , $arg2) { 
[. .] 

1 

1. .] 

} 

The form of the syntax is as described, in order, in the following list: 

■ The special form class, followed by the name of the class that you want to define. 

■ An optional extension clause, consisting of the word extends and then the name of the 
class that should be inherited from. 

■ A set of braces enclosing any number of variable declarations and function definitions. 
Variable declarations start with the special form public, private, or protected, which 
is followed by a conventional $ variable name; they may also have an initial assignment to 
a constant value. Function definitions look much like standalone PHP functions but are 
local to the class. 

As an example, consider the simple class definition in Listing 20-1, which prints out a box of text 
in HTML. 



LISTING 20-1 



TextBox.php 

class TextBoxSimpl e ( 

public $body_text = "my text"; 
function display!) { 

print ( "<TABLE BORDER=lXTRXTD>$thi s - >body_text " ) ; 

print("</TDX/TRX/TABLE>") ; 

1 
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This is an extremely simple class definition. It has no parent (and, therefore, no extends clause). 
It has a single member variable (the variable $body_text) and a single member function (the 
function d i s p 1 ay ( ) ). The display function simply prints out the text variable, wrapped up in an 
HTML table definition. 

Accessing member variables 

In general, the way to refer to a member variable from an object is to follow a variable containing the 
object with - > and then the name of the member. So if we had a variable $ box containing an object 
instance of the class TextBox, we could retrieve its body_text variable with an expression like: 

$text_of_box = $box- >body_text ; 

However, when we are writing code within a member function, we haven't yet created the object 
instance, and so we have no variable like $ box to refer to. The answer is the magic variable $thi s, 
which (when used inside a member function of a class) refers to the object instance itself. Note that this 
is how the di spl ay ( ) function in Listing 20-1 retrieves the text it displays ($thi s->body_text). 

This syntax can be a little counterintuitive. You might think that we could simply refer to $body_text 
in functions within our TextBox class because we have declared it in the class definition, but in fact the 
only way to get to members from within a member function definition is via $ t h i s . Notice also that the 
syntax for this access does not put a $ before the member variable name itself, only the $ t h i s variable. 

Creating instances 

After we have a class definition, the default way to make an instance of that class is by using the new 
operator. If we have already defined the class TextBox as in Listing 20-1, we can make an instance 
of it, and then use it, like this: 

$box = new TextBoxSi mpl e ; 
$box->di spl ay ( ) ; 

The result of evaluating this code will be to print an HTML fragment containing a table definition 
enclosing the text my text. (Not especially useful, but it's a start.) 

Constructor functions 

One way in which our TextBox class is not very useful is that its instances do not contain any data 
when they are created, except for the static initialization of the variable $body_text. The point of 
such a class would be to display arbitrary pieces of text, not the same message every time. It's true that 
we could make an instance and then install the right data in the instance's internal variables, like this: 

$box = new TextBoxSi mpl e ; 
$box->body_text = "custom text"; 
$box->di spl ay ( ) ; 

But that would be cumbersome and error-prone as we build more complex objects. 
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The correct way to arrange for data to be appropriately initialized is by writing a constructor func- 
tion — a special function called construct( ), which will be called automatically whenever a 

new instance is created. 

Modifying our previous example to include a constructor function gives us Listing 20-2. 



LISTING 20-2 



TextBox redefined 

class TextBox ( 

public $body_text = "my text"; 
// Constructor function 

public function const ruct ( $text_i n ) { 

$thi s - >body_text = $text_in; 

} 

function display!) { 

print ( "<TABLE BORDER=lXTRXTD>$this->body_text" ) ; 
pri nt ( "</TDX/TRX/TABLE>" ) ; 

) 

} 

// creating an instance 

$box = new TextBoxC "custom text"); 

$box->di spl ay ( ) ; 



As the preceding code is executed, the output is an HTML table enclosing the text custom text. 
„«_,-.„.. . . . . - — — ■ 

j J r/_T_r; There should be only one constructor function per class definition. Defining 

more than one such function is syntactically legal, but pointless, as only the defi- 
nition that occurs last will be in effect. If you'd like to have different constructors to handle different 
numbers and types of input arguments, see the section "Simulating Polymorphism" later in this chapter. 

Inheritance 

PHP class definitions can optionally inherit from a parent class definition by using the extends 
clause. The syntax is: 

class Child extends Parent { 
definition body> 

} 

The effect of inheritance is that the child class (or subclass or derived class) has the following 
characteristics: 

■ Automatically has all the member variable declarations of the parent class (or superclass or 
base class) 

■ Automatically has all the same member functions as the parent, which (by default) will 
work the same way as those functions do in the parent 
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In addition, the child class can add on any desired variables or functions simply by including them 
in the class definition in the usual way. 

In Listing 20-2, we defined a class called TextBox; now we'll define a class called TextBoxHeader 
that extends TextBox (see Listing 20-3). TextBoxHeader has two member variables: one ( $body_ 
text) that it receives through inheritance from TextBox, and another ($header„text) that it 
defines itself. Like TextBox, it has a constructor function and a function called di s p 1 ay. This func- 
tion definition overrides the display function in TextBox. 



LISTING 20-3 



TextBoxHeader 

class TextBoxHeader extends TextBox 
{ 

public $header_text ; 
// CONSTRUCTOR 

public function construct ( $header 

$body_text_i n ) { 
$thi s ->header_text = $header_text 
$thi s->body_text = $body_text_i n ; 

} 

// MAIN DISPLAY FUNCTION 
public function display!) { 

$header_html = 

$this->ma ke_header ( $thi s ->header_text ) ; 

$body_html = $thi s ->ma ke_body ( $thi s ->body_text ) ; 

print ("<TABLE BORDER=lXTRXTD>\n" ) ; 

pri nt( " $header„html \ n " ) ; 

print ( "</TDX/TRXTRXTD>\n" ) ; 

pri nt ( " $body_html \n " ) ; 

pri nt( "</TDX/TRX/TABLE>\n" ) ; 

} 

// HELPER FUNCTIONS 
public function make_header ($text) ( 
return ( $text ) ; 

} 

public function make_body ($text) ( 
return ( $text ) ; 

} 



text_i n , 
i n ; 



321 



Part III 



More PHP 



Overriding functions 

Function definitions in child classes override definitions with the same name in parent classes. This 
just means that the overriding definition in the more specific class takes precedence and will be the 
one actually executed. In the example in Listing 20-3, the TextBoxHeader class defines a function 
called d i s p 1 a y ( ) , which means that executing the following code: 

$text_box_header = new TextBoxHeader ( "The Header", "The Body"); 
$text_box_header->di spl ay ( ) ; 

will result in a call toTextBoxHeader's display() function, not the di spl ay ( ) function in 
T e x t B o x . The resulting HTML output prints a box with a header of The Header and a body of T h e 
Body. The more specific d i s p 1 a y ( ) function takes total responsibility here; there is no call, either 
explicit or implicit, to the di spl ay ( ) function defined in the TextBox class. (Although PHP makes 
no such implicit calls, it is possible to explicitly call functions that have been defined in a parent 
class — see "Calling parent functions" in the "Advanced OOP Features" section later in the chapter.) 

The flip side of overriding functions, however, is that whenever a subclass does not override a 
parental definition, the parent's definition will be in effect. Note that the "helper" functions in the 
definition of TextBoxHeader don't really do anything interesting, and you might wonder why we 
bothered to separate them out. The answer is that this provides an opportunity for an inheriting 
class to do something interesting with those functions by selectively overriding them — or not, as 
they see fit. 

PHP5 (as a result of Zend Engine 2) introduced the final keyword. If, in the previous example, the 
definition of di spl ay ( ) in class TextBox had looked like this: 

final function displayO ( 

pri nt( "<TABLE BORDER=lXTRXTD>$this->body_text" ) ; 
print ( "</TDX/TRX/TABLE>" ) ; 

} 

then the method could not have been overridden by a definition in TextBoxHeader. 

It is possible to declare whole classes final and individual methods, but not individual properties. 

Chained subclassing 

PHP does not support multiple inheritance but does support chained subclassing. This is a fancy way 
of saying that, although each class can have only a single parent, classes can still have a long and 
distinguished ancestry (grandparents, great-grandparents, and so on). Also, there's no restriction on 
family size; each parent class can have an arbitrary number of children. 

As example, see Listing 20-4, where our definition of TextBoxBol dHeader inherits from 
TextBoxHeader, which in turn inherits from TextBox. 
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TextBoxBoldHeader 

class TextBoxBoldHeader extends TextBoxHeader I 
// CONSTRUCTOR 

public function construct ( $header_text_i n , 

$body_text_i n ) { 
$thi s->header_text = $header_text_i n ; 
$thi s->body_text = $body_text_i n ; 

} 

// HELPER FUNCTIONS 
// make_header overrides parent 
public function make_header ($text) ( 
return( "<B>$text</B>" ) ; 

} 



This definition of TextBoxBol dHeader is minimal; it defines no new member variables and defines 
only one function besides its constructor. That new function (make_header( )) overrides the defini- 
tion in its parent. Now what happens when we actually use this definition in the usual way? 

$text_box_bol d_header = 

new TextBoxBol dHeader ( "The Header", "The Body"); 
$text_box_bol d_header->di spl ay ( ) ; 

It's worth looking in a bit of detail to see exactly what happens when we make these two function calls. 

First, when we call the constructor (TextBoxBol dHeader ( )), the constructor sets variables that 
were defined in the grandparent (TextBox) and the parent (TextBoxHeader), respectively, and 
returns a new instance of TextBoxBol dHeader. 

Second, when we call $text_box_bol d_header->di spl ay ( ) , the call sequence is: 

1. NodisplayO function is found in TextBoxBol dHeader, so the version from 
TextBoxHeader is called. 

2. The first function call in that version ofdisplayO isto$this->ma ke_header ( ) . 
Remember that $ t h i s refers to the object instance that we started with, which happens to 
be an instance of TextBoxBol dHeader, so PHP looks first of all for a definition from that 
class. It finds one and uses it to return the header string wrapped up in the HTML bold 
text construct (<BX/B>). 

3. The second function call is to $thi s - >ma ke_body ( ) . This time, though, there is no over- 
riding definition in TextBoxBol dHeader, so the version from TextBoxHeader is used. 
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The upshot is that, in defining TextBoxBol dHeader,we mostly exploited the behavior of the par- 
ent class but were able to change its behavior slightly by overriding a single member function. 

Modifying and assigning objects 

Prior to PHP5, when you assigned an object to a variable or passed it to a function, that object was 
actually copied, bit for bit, into the variable or function scope. That caused tremendous hassles, and 
programmers had to be careful to devise clever workarounds for the problems. 

The problem was solved with PHP5, which incorporates Zend Engine 2. Zend Engine 2 copies by 
reference, rather than explicitly. That is, several variables can point to the exact same object and 
expect changes made via one reference to be reflected in the others. 

Scoping issues 

Before we move onto the more advanced features of PHP's version of OOP, it's important to nail 
down issues of scope — that is, which names are meaningful in what way to different parts of our 
code. It may seem as though the introduction of classes, instances, and member functions have 
made questions of scope much more complicated. Actually, though, there are only a few basic rules 
we need to add to make OOP scope sensible within the rest of PHP: 

■ Names of member variables and member functions are never meaningful to calling code 
on their own — they must always be reached via the - > construct (or, as we'll see in the 
"Advanced OOP Features" section, the : : construct). This is true both outside the class 
definition and inside member functions. 

■ The names visible within member functions are exactly the same as the names visible 
within global functions — that is, member functions can refer freely to other global func- 
tions but can't refer to normal global variables unless those variables have been declared 
global inside the member function definition. 

These rules, together with the usual rules about variable scope in PHP, are respected in the inten- 
tionally confusing example in Listing 20-5. What number would you expect that code to print when 
executed? 



LISTING 20-5 



Confusing scope 

$my_global = 3; 

public function my_function ( $my_i nput ) { 
global $my_gl obal ; 
return ( $my_gl obal * $my_input); 

} 
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class MyClass ( 

protected $my_member ; 

f uncti on construct( $my_constructor_i nput ) 

$thi s->myjnember = 

$my_constructor_i nput ; 

} 

public function myMemberFuncti on ($my_inputl 
global $my_gl obal ; 
return ( $my_gl obal * 
$my„input * 

my_f uncti on ( $thi s ->my_member ) ) ; 



$my_i nstance = new MyClass(4); 
print("The answer is: " . 

$my_i nstance->myMemberFunction(5)) ; 



The answer is: 180 (or 3 * 5 * (3 * 4)). If any of these numerical variables had been undefined when 
multiplied, we would have expected the variable to have a default value of 0, making the answer 
have a value of 0 as well. This would have happened if we had: 

■ Left out the global declaration in my _f u n c t i o n ( ) 

■ Left out the global declaration in myMemberFuncti on ( ) 

■ Referred to $my_member rather than $thi s->my_member 



Advanced OOP Features 

In the previous section, we presented a minimal subset of PHP's object-oriented constructs that 
let you use the most basic OOP techniques. In this section, we look at some of the slightly more 
unusual constructs, techniques, and gotchas that can get you into more trouble. (We defer any 
discussion of the functions that give meta-information about classes and objects to the section 
"Introspection Functions," later in this chapter.) 

Public, Private, and Protected Members 

Unless you specify otherwise, properties and methods of a class are public. That is to say, they may 
be accessed in three possible situations: 

■ From outside the class in which it is declared 

■ From within the class in which it is declared 

■ From within another class that implements the class in which it is declared 
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If you wish to limit the accessibility of the members of a class, you should use private or 
protected. 

Private members 

By designating a member private, you limit its accessibility to the class in which it is declared. The 
private member cannot be referred to from classes that inherit the class in which it is declared and 
cannot be accessed from outside the class. 

Making a member private is straightforward: 

class MyClass ( 

private ScolorOfSky = "blue"; 
SnameOfShip = "Java Star"; 

public function const ruct ($ i ncomi ngVa 1 ue ) ( 

// Statements here run every time an instance of the class 
// is created. 

} 

public function my Publ i cFuncti on ($my_input) ( 
r e t u r n ( " I ' m visible!"); 

} 

private function myPri vateFuncti on ($my_input) I 
gl obal $my_gl obal ; 
return ( $my_gl oba 1 * 
$my_input * 

my_f unct i on ( $thi s - >my_member ) ) ; 

1 

) 

When that class is inherited by another class (using extends), my Publ i cFuncti on ( ) will be vis- 
ible, as will SnameOfShip. The extending class will not have any awareness of or access to my Pri - 
vateFunction, because it is declared private. 

Protected members 

A protected property or method is accessible in the class in which it is declared, as well as in classes 
that extend that class. Protected members are not available outside of those two kinds of classes, 
however. 

Here is a different version of My C 1 a s s : 
class MyClass ( 

protected ScolorOfSky = "blue"; 
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SnameOf Shi p = "Java Star"; 

public function const ruct ( $i ncomi ngVal ue ) ( 

// Statements here run every time an instance 

// of the class is created. 

} 

public function myPubl i cFuncti on ($my_input) { 
return ("I'm visible!"); 

) 

protected function myProtectedFuncti on ($my_input) ( 
global $my_gl obal ; 
return ( $my_gl obal * 
$my_input * 

my_f uncti on ( $thi s ->my_member ) ) ; 

} 

I 

If we had another class that extended My CI ass, it would be able to see and use $colorOfSky and 
myProtectedFuncti on ( ), just as if they were public. It would not, however, be possible to call 
MyCl ass : : $col orOfSky. You'll read more about the : : syntax later in this chapter. 

Interfaces 

In large object-oriented projects, there is some advantage to be realized in having standard names 
for methods that do certain work. For example, if many classes in a software application needed to 
be able to send e-mail messages, it would be desirable if they all did the job with methods of the 
same name and had the same number and type of arguments. 

interface Mail { 

public function s e n d M a i 1 ( ) ; 

1 

Then, if another class implemented that interface, like this: 

class Report implements Mail { 

// Definition goes here 

) 

it would be required to have a method called sendMai 1 . It's an aid to standardization. 

Constants 

A constant is somewhat like a variable, in that it holds a value but is really more like a function 
because a constant is immutable. Once you declare a constant, it does not change. Declaring one is 
easy, as is done in this version of My C 1 a s s : 
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class MyClass { 

const requi redMargi n = 1.3; 

function construct ($ i ncomi ngVal ue ) ( 

// Statements here run every time an instance of the class 
// is created. 

} 

) 

In that class, requiredMarginisa constant. It is declared with the keyword const, and under no 
circumstances can it be changed to anything other than 1.3. Note that the constant's name does not 
have a leading $ , as variable names do. 

Abstract Classes 

An abstract class is one that cannot be instantiated, only inherited. You declare an abstract class 
with the keyword abstract, like this: 

abstract class MyAbstractCl ass I 

abstract function myAbstractFuncti on ( ) I 

} 

1 

Note that function definitions inside an abstract class must also be preceded by the keyword 
abstract. It is not legal to have abstract function definitions inside a nonabstract class. 

Simulating class functions 

Some other OOP languages make a distinction between instance member variables, on the one hand, 
and class or static member variables on the other. Instance variables are those that every instance of a 
class has a copy of (and may possibly modify individually); class variables are shared by all instances 
of the class. Similarly, instance functions depend on having a particular instance to look at or 
modify; class (or static) functions are associated with the class but are independent of any instance 
of that class. 

In PHP, there are no declarations in a class definition that indicate whether a function is intended 
for per-instance or per-class use. But PHP does offer a syntax for getting to functions in a class even 
when no instance is handy. The : : syntax operates much like the - > syntax does, except that it 
joins class names to member functions rather than instances to members. For example, in the fol- 
lowing implementation of an extremely primitive calculator, we have some functions that depend on 
being called in a particular instance and one function that does not: 

class Cal cul ator 
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{ 

public $current = 0; 
public function add($num) { 
$thi s->cunrent += $num; 

} 

public function s ubt nact ( $num ) ( 
$this->cunrent -= $num; 

} 

public function getValue() { 
neturn ( $current ) ; 

} 

publ i c f uncti on pi ( ) j 

return(M_PI ) ; // the PHP constant 

} 

} 

We are free to treat the p i ( ) function as either a class function or an instance function and access it 
using either syntax: 

$cal c_i n stance = new Calculator; 
$cal c_i nstance->add(2) ; 
$cal c_i nstance->add(5) ; 
print( "Current value is " . 

$cal c_i nstance->current ."<BR>"); 
print(" Value of pi is " . 

$cal c_i nstance->pi ( ) . "<BR>"); 
print(" Value of pi is " . 

Calculator: :pi() . "<BR>"); 

This means that we can use the p i ( ) function even when we don't have an instance of Calculator 
at hand. The Calculator class has to be accessible in either case, though, meaning that it has to 
have been imported with a requi re_once statement, or something similar. 

Calling parent functions 

Asking an instance to call a function will always result in the most specific version of that function 
being called, because of the way overriding works. If the function exists in the instance's class, the 
parent's version of that function will not be executed. 

Sometimes it is handy for code in a subclass to explicitly call functions from the parent class, even if 
those names have been overridden. It's also sometimes useful to define subclass functions in terms 
of superclass functions, even when the name is available. 

Calling parent constructors 

In the section "Inheritance" earlier in this chapter, we showed you code (see Listing 20-3) where 
both subclass and superclass had constructors, and both constructors set a variable that was defined 



329 



Part III 



More PHP 



by the superclass. This might be stylistically dodgy, but more importantly, we would like to avoid 
duplicating work across the two constructors, especially if a lot of code is involved. 

Instead of writing an entirely new constructor for the subclass, let's write it by calling the parent's 
constructor explicitly and then doing whatever is necessary in addition for instantiation of the sub- 
class. Here's a simple example: 

class Name 
{ 

publ i c $_f i rstName ; 
publ i c $_1 astName ; 

public function const ruct ( $fi rst_name , $last_name) 

( 

$thi s->_fi rstName = $first_name; 
$thi s->_l astName = $last_name; 

1 

public function renameO { 
return ( $thi s ->_1 astName . 

$ t h i s - >_f i rstName) ; 

} 

} 

class NameSubl extends Name 
{ 

public $_mi ddl elni ti al ; 

public function NameSubl ( $fi rst_name , $mi ddl e_i ni ti al , 
$last_name) 1 
Name: :Name($fi rs t_name , $1 ast_name ) ; 
$ t hi s - >_m i d d 1 e I n i t i a 1 = $ m i d d 1 e_i n i t i a 1 ; 

1 

public function renameO { 
return ( Name : : rename( ) . " " . 

$ t h i s - >_m i d d 1 e I n i t i a 1 ) ; 

1 

} 

In this example, we have a parent class (Name), which has a two-argument constructor, and a sub- 
class (NameSubl), which has a three-argument constructor. The constructor of NameSubl functions 
by calling its parent constructor explicitly using the : : syntax (passing two of its arguments along) 
and then setting an additional field. Similarly, NameSubl defines its nonconstructor rename ( ) func- 
tion in terms of the parent function that it overrides. 

It might seem strange to callName: :Name() here, without reference to $thi s. The good news is 
that both $ t h i s and any member variables that are local to the parent are available to a parent func- 
tion when invoked from a child instance. 
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In a sense, constructor functions in a subclass override the constructors in superclasses. (We say "in 
a sense" because we usually only say that one function overrides another if the two functions have 
the same name; a subclass constructor and a superclass constructor always have different names.) 

As you saw in the previous section, if you want both the subclass constructor and the superclass 
constructor to be called, you must include code in the subclass to call the superclass code explicitly. 
Beginning with PHP4, if a subclass lacks a constructor function and a superclass has one, the super- 
class's constructor will be invoked. The most specific constructor that can be found (if any) will be 
called — anything else is up to the programmer. 



One neat trick offered by some OOP languages (and not offered by PHP) is automatic overloading 
of member functions. This means that you can define several different member functions with the 
same name but different signatures (number and types of arguments). The language itself takes care 
of matching up calls to those functions with the right version of the function, based on the argu- 
ments that are given. 

PHP does not offer such a capability, but the loose typing of PHP lets you take care of one half of the 
overloading equation — you can define a single function of a given name that behaves differently 
based on the number and types of arguments it is called with. The result looks like an overloaded 
function to the caller (but not to the definer). 

Here's an example of an apparently overloaded constructor function: 

class MyClass 
{ 

public $string_var = "default string"; 
publ i c $num_va r = 42 ; 

public function construct( $argl ) { 



if ( i s_st ri ng( $a rgl ) ) { 
$thi s - >st r i ng_va r = $argl; 

) 

el seif ( is_int($argl) | 

i s_doubl e ( $a rgl ) ) ( 
$thi s->num_var = $argl; 

} 



Simulating method overloading 



$ i n s t a n 
$ i n s t a n 



c 



c 



el = n 
e2 = n 



ew 



ew 



MyCl 
MyCl 



as 



as 



s 



s 



( "new stri ng" ) ; 
(5) ; 
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The constructor of this class will look to its caller as though it is overloaded, with different behavior 
based on the type of its inputs. You can also vary behavior based on the number of arguments by 
testing the number of arguments supplied by the caller. 



I C H Cj£/~£)-'P '''f ' n ^ ormat ' on on wrmn g functions with variable numbers of arguments, see Chapter 26. 
fc3^*^"fi™«AB The techniques work the same way with member functions in classes as they do with stand- 



alone user-defined functions. 



Serialization 

Serialization of data means converting it into a string of bytes in such a way that you can produce 
the original data again from the string (via a process known, unsurprisingly, as unserializatiori). After 
you have the ability to serialize/unserialize, you can store your serialized string pretty much any- 
where (a system file, a database, and so on) and recreate a copy of the data again when needed. 

PHP offers two functions, serial 1 z e ( ) and u n s e r i a 1 i z e ( ) , which take a value of any type 
(except type resource) and encode the value into string form and decode again, respectively. The 
PHP3 implementation of object serialization wasn't very useful because member function definitions 
didn't survive the serialization/unserialization process; beginning with version 4, however, PHP 
robustly recreates all important aspects of the instance from the string, as long as the class definition 
is available to the code where u n s e r i a 1 i z e ( ) is called. 

Here is a quick example, which we'll extend later in this section: 

class CI assToSeri al i ze ( 

public SstoredStatement = "data"; 

public function construct($statement) ( 

$thi s->storedStatement = $statement; 

1 

public function display () 

{ 

pri nt( $thi s->storedStatement . "<BR>"); 

1 

) 



$instancel = 

new CI assToSeri al i ze( "You ' re objectifying me!"); 
$serialization = serial ize($instancel); 
$instance2 = unserialize($serialization); 
$instance2->display( ) ; 



This class has just one member variable and a couple of member functions, but it's sufficient to dem- 
onstrate that both member variables and member functions can survive serialization. We create an 
object, convert it to a serialized string, convert it back to a new instance, and the printed result is 
the accurate complaint (You ' re objecti fyi ng me !). 

Of course, there is no point in serializing and unserializing an object in the same script. 
Serialization is only worthwhile when we expect the serialized string to outlive the script (and the 
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variable) that it currently lives in and be reincarnated in another execution. This may be because we 
store the serialization in a file or a database and read it back in again. It can also happen automati- 
cally as a result of PHP's session mechanism — variables that are registered as belonging to a session 
will be serialized and unserialized from page to page. 



For more on how the session mechanism uses serialization, see Chapter 26. 



Sleeping and waking up 

PHP provides a hook mechanism so that objects can specify what should happen just before 

serialization and just after unserialization. The special member function si eep( ) (that's two 

underscores before the word s 1 eep), if defined in an object that is being serialized, will be called 
automatically at serialization time. It is also required to return an array of the names of variables 
whose values are to be serialized. This offers a way to not bother serializing member variables that 
are not expected to survive serialization anyway (such as database resources) or that are expensive 

to store and can be easily recreated. The special function wa keup ( ) (again, two underscores) 

is the flip side — it is called at unserialization time (if defined in the class) and is likely to do the 

inverse of whatever is done by s 1 eep ( ) (restore database connections that were dropped by 

sleep() or recreate variables that sleepO said not to bother with). 

You may wonder why these functions are necessary — couldn't the code that calls s e r i a 1 i ze ( ) 
also just do whatever is necessary to shut down the object? Actually, it's very much in keeping with 
OOP to include such knowledge in the class definition rather than expecting the code using the 
objects to know about their special needs. Also the calling code may have no knowledge of the 
object's internals at all (as in the code that serializes all session objects). The author of the class is 
uniquely qualified to say what should happen when an instance is sent away or revived. 

As an example of how to use these functions, here is the previous serialization example, augmented 
with an extra variable, and the sleepO and wakeupO functions: 

class CI assToSeri al i ze2 { 

public SstoredStatement = "data"; 

public SeasilyRecreatable = "data again"; 

public function construct ( $statement ) { 

$thi s->storedStatement = $statement; 
$thi s->easi lyRecreatabl e = 

$thi s->storedStatement . " Again!"; 

1 

public function sleepO ( 

// Could include DB cleanup code here 
return a rray ( ' storedStatement ' ) ; 

} 

public function wakeupO ( 

// Could include DB restoration code here 
$thi s->easi lyRecreatabl e = 

$thi s - >storedStatement . " Again!"; 
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public function display () 
{ 

print($this->easilyRecreatable . "<BR>"); 

1 

} 

$instancel = 

new CI assToSeri al i ze2 ( " You ' re objectifying me!"); 
$serialization = serial ize($instancel); 
$instance2 = unseri al i ze( $seri al i zati on ) ; 
$instance2->display( ) ; 

The variable called SeasilyRecreatable is meant to stand in for a piece of data that is (1) expen- 
sive to store and (2) implied by the other data in the class anyway. The definition of s 1 eep ( ) 

does no cleanup itself, but it returns an array that contains only one variable name and does not 
include easilyRecreatable.At serialization time , only the value of the variable storedState- 

ment is included in the string. When the object is recreated, the wa keup( ) function assigns a 

value into $this->easilyRecreatable, which is then displayed: You're ob j ect i fy i ng me ! 
Agai n ! 

Serialization gotchas 

The serialization mechanism is pretty reliable for objects, but there are still a few things that can trip 
you up: 

■ The code that calls u n s e r i a 1 i z e ( ) must also have loaded the definition of the relevant 
class. (This is also true of the code that calls s e r i a 1 i ze ( ) too, of course, but that will 
usually be true because the class definition is needed for object creation in the first place.) 

■ Object instances can be created from the serialized string only if it is really the same string 
(or a copy thereof). A number of things can happen to the string along the way, if stored 

in a database (make sure that slashes aren't being added or subtracted in the process), or if 
passed as url or form arguments. (Make sure that your URL-encoding/decoding is pre- 
serving exactly the same string and that the string is not long enough to be truncated by 
length limits.) 

■ If you choose to use s 1 eep ( ) , make sure that it returns an array of the variables to 

be preserved; otherwise no variable values will be preserved. (If you do not define a 

s 1 eep ( ) function for your class, all values will be preserved.) 



Introspection Functions 

While PHP lacks some features of full OO languages like Java or C++, it is surprisingly good in the 
esoteric area of introspection. (It's the classes and objects that get introspective here, not the pro- 
grammer.) Introspection allows the programmer to ask objects about their classes, ask classes about 
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their parents, and find out all the parts of an object without have to crunch the source code to do it. 
Introspection also can help you to write some surprisingly flexible code, as you will see. 

Function overview 

Most of this section will be example-driven, but we begin by looking at the introspection functions 
provided by PHP. Table 20-1 summarizes these functions, what they do, and what version of PHP 
introduced them. (This table is essentially a reframing of information from the online manual; we 
offer it here mainly because it highlights features that we found somewhat confusing the first time 
we studied the manual.) 



TABLE 20-1 



Class/Object Functions 


Function 


Description 


Operates 
on Class 
Names 


Operates 
on 

Instances 


As of PHP 
Version 


get_cl ass ( ) 


Returns the name of the class an 
object belongs to. 


No 


Yes 


4.0.0 


get_pa rent_ 
cl a s s C ) 


Returns the name of the parent class 
of the given instance or class. 


Yes (as 

n( DUD 

OT rrir 

v.4.0.5) 


Yes 


4.0.0, 
4.U.O 


cl ass_ 
exi sts ( ) 


Returns TRUE if the string argument is 
the name of a class, FALSE otherwise. 


Yes 


No 


4.0.0 


get_ 

decl a red_ 
cl asses ( ) 


Returns an array of strings 
representing names of classes defined 
in the current script. 


N/A 


N/A 


4.0.0 


i s_subcl ass_ 
of ( ) 


Returns TRUE if the class of its first 
argument (an object instance) is a 
subclass of the second argument (a 
class name), FALSE otherwise 


No 


Yes 


4.0.0 


get_cl ass_ 
vars ( ) 


Returns an associative array of var/ 
val ue pairs representing the name 
of variables in the class and their 
default values. Variables without 
default values will not be included. 


Yes 


No 


4.0.0 


get_ob j ect_ 
va rs ( ) 


Returns an associative array of var/ 
val ue pairs representing the name 
of variables in the instance and their 
default values. Variables without 
values will not be included. 


No 


Yes 


4.0.0 



continued 
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1 (continued) 








Function 


Description 


Operates 
on Class 
Names 


Operates 
on 

Instances 


As of PHP 
Version 


methocL 
exi sts ( ) 


Returns TRUE if the first argument 
(an instance) has a method named by 
the second argument (a string) and 
FALSE otherwise. 


No 


Yes 


4.0.0 


get_cl ass_ 
methods ( ) 


Returns an array of strings 
representing the methods in the 
object or instance 


Yes 


Yes (as of 
V4.0.6) 


4.0.0, 
4.0.6 


cal l_user_ 
methocL 
array ( ) 


Same as cal l_user_ 
method ( ), except that it expects 
its third argument to be an array 
containing the arguments to the 
method. 


No 


Yes 


4.0.5 



These functions break down into the following four broad categories: 

■ Getting information about the class hierarchy 

■ Finding out about member variables 

■ Finding out about member functions 

■ Actually calling member functions 

The first group of functions (get_class() through instanceof( )) deal with discovering what 
classes exist, asking an object about its class, and discovering class inheritance relationships. Some 
of these functions start with an instance of an object, some start with the class name as a string, and 
some are happy with either one. (We've included columns in the table to try to clarify this.) Note 
that after we have the get_class( ) function, it's easy to satisfy functions that require a class as 
input; for example, if get_parent_cl ass ( ) insists on a class name, and we want to know the par- 
ent class of an object instance, we could just wrap it like this: 

$parent_cl ass = get_pa rent_cl ass ( get_cl ass ( $my_i nstance ) ) ; 

Bear in mind that as of PHP4.3, the constant C LASS exists. It contains the class name. 

Going in the other direction (trying to satisfy a function that wants an instance when all we have is a 
class) would be more problematic because you don't want to instantiate a class just to ask questions of it. 

The second group of functions (get_cl ass„va rs ( ) , get_ob ject_va rs ( )), return an associative 
array containing member variables and their values. The keys of these arrays are the names of the 
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variables as strings (without leading $ symbols), and the array values are the values of those vari- 
ables in the object or class. In both cases (for reasons unknown to your authors), only member vari- 
ables that actually have a value are returned. 

The difference between get_cl ass_va rs ( ) and get_ob j ect_vars ( ) is subtle, but it's more than 
just a question of what type of input they prefer. The get_cl ass_va rs ( ) function returns informa- 
tion about variables and default values as they exist in the class definition itself, independent of any 
instance; get_ob j ect_va rs ( ) returns information about the current state of a particular instance. 
For example, consider this class definition and use: 

class Example ( 

public $varl = "initialized"; 
public $var2 = "initialized"; 
public $var3; 
public $var4; 

public function constructO ( 

$thi s->van3 = "set" ; 
$this->vanl = "changed"; 

1 

1 

$example = new ExampleO; 

pri nt_r ( get_cl ass_va rs ("Example")); 

pri nt_r ( get_ob j ect_va rs (lexample)); 

For the first call (to get_cl ass_va rs ( )), we should expect to find va rl and va r2 both bound to 
"initial i z e d " as in the class definition itself. The second call (to g e t_o b j e c t_v a r s ( ) ) should 
return bindings ofvarl, var2, and va r3 to "changed ", "initialized", and "set", respec- 
tively. In neither case will either function retrieve va r4. 

The third group of functions (method_exi sts ( ) , get_cl ass_methods ( )) manipulate member 
function names as strings. The first allows you to ask an instance if it contains a given function, and 
the second recovers all function names from an instance or class. (Notice that we don't need two 
separate functions as we did with get_class_vars( ) and get_object_vars(); PHP doesn't 
offer you a way to add or delete member functions from instances on the fly.) 

Finally, the fourth group lets you apply method names (presumably recovered using functions from 
the third group) to instances. But these are probably best explained by example, so let's dive in. 

Example: Class genealogy 

Consider the following, somewhat confusing, class hierarchy, 
class Col or { } 

class Control extends Ulelement {} 
class Widget extends Control { ) 
class Button extends widget () 
class Pulldown extends Widget () 
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class Clicker extends Button {) 

class Blue extends Color {} 

class Displayer extends Ulelement {} 

class UI El ement { } 

class LightBlue extends Blue () 

Now imagine that we'd like to have a better visualization of this tangle, just for purposes of docu- 
mentation. For starters, it's pretty easy to use the get_parent_cl ass( ) function to figure out the 
classes that a given class descends from: 

public function pr i nt_ancest ry ( $cl ass_name ) ( 
print(" Class ancestry: "); 
pri nt_ancest ry_aux ( $cl ass_name ) ; 
print("<BR>") ; 

} 

public function pri nt_ancestry_aux ( $cl ass_name ) ( 
pri nt( "$cl ass_name" ) ; 

if ($parent = get_pa rent_cl ass ( $cl ass_name ) ) 1 
pri nt( " => " ) ; 

pri nt_ancest ry_a ux($parent) ; 

1 

} 

pri n trances try ( "CI i cker" ) ; 

Which gives us the somewhat informative output: 

Class ancestry: Clicker => button => widget => control => uielement 

(Notice that our retrieved class names have become lowercase. This happens to user-defined classes, 
whereas prior to PHP 6, built-in classes should have their capitalization intact.) 

Getting a view of the entire class tree is a little bit harder, because PHP doesn't offer a straight- 
forward way to retrieve child classes given a parent class. Our recourse is the get_decl a red_ 
classes function, which tells us all the classes that are defined in the current script — we can then 
somewhat inefficiently do paternity tests on all known classes to discover the children of a given 
class (see Listing 20-6). 



LISTING 20-6 



Class genealogy 



public function same_cl ass_name ($stringl, $string2) 
return ( ( s t rtol ower ( $s t r i ngl ) ) == 
( s t rtol ower ( $string2))); 



public function get_chi 1 d_cl asses ($parent) ( 
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$all_classes = get_decl ared_cl asses () ; 
$ c h i 1 dren = array ( ) ; 

foreach ( Sal l_cl asses as $candidate) ( 
if ( same_cl ass_name( Sparent , 

get_pa rent_cl ass($candidate)) && 
! same_cl ass_name( Sparent , $candidate)) ( 
a r ray_push ( Schildren, $candidate); 

) 

} 

return($children) ; 



public function pri nt_cl ass^tree () ( 
$all_classes = get_decl ared_cl asses () ; 
print("<PRE>"); 
printCCLASS H I ERARCHY : \n " ) ; 

foreach ( Sal l_cl asses as Scandidate) { 
if (! get_pa rent_cl ass ( Scandi date ) ) { 
pri nt_cl ass_t ree_a ux($candidate, 0); 

1 

} 

print( "</PRE>" ) ; 



public function pri nt_cl ass_tree_aux (Sparent, Slevel) ( 
for ($x = 0; $x < Slevel; $x++) { 
p r i n t ( " " ) ; 

1 

pr i nt ( " Spa rent<BR> " ) ; 

Schildren = get_chi 1 d_cl asses ( Spa rent ) ; 
foreach (Schildren as Schild) { 

pri nt_cl ass_tree_aux( Schi 1 d , Slevel + 1); 

1 

1 

pri nt_cl ass_tree( ) ; 



We start off this listing by defining what it means for two class names to be the same. This may be 
overkill, but converting every name to lowercase before comparison lets us stop worrying about 
whether we'll be tripped up by case issues. Then we define a general function to retrieve child 
classes (inefficiently, but it should make no difference unless your class hierarchy grows to be very, 
very large). The pri nt_cl ass_tree ( ) function essentially recovers all orphans or roots (classes 
without parents) and prints each one individually as a tree. The auxiliary function handles printing 
a rooted tree — first the parent and then indented children. Finally, we wrap the whole thing in a 
<PREX/PRE> construct so we can just use spaces for indenting. The result looks like this: 

CLASS HIERARCHY: 
stdCl ass 
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PHP_Incompl ete_Cl ass 

OverloadedTestClass 
Di rectory 
col or 
bl ue 

1 i ghtbl ue 
ui el ement 
control 
wi dget 

button 

cl i cker 
pull down 
di spl ayer 

The first few classes printed are unfamiliar and not defined in your code file. These either belong to 
the PHP implementation itself or to auxiliary packages that you have compiled — the precise classes 
that you see when you execute this code may vary. 

Example: matching variables and DB columns 

One frequent use for PHP objects in database- driven systems is as a wrapper around the entire data- 
base API. The theory is that the wrapper insulates the code from the specific database system, which 
will make it trivial to swap in a different RDBMS when the technical needs change. (We've never 
seen it work out quite this way in practice, but . . . don't get us started.) Another use that is almost as 
common (and that your authors like better) is to have object instances correspond to database result 
rows. In particular, the process of reading in a result row looks like instantiating a new object that 
has member variables corresponding to the result columns we care about, with extra functionality 
in the member functions. As long as the fields and columns match up (and as long as you can afford 
object instantiation for every row), this can be a nice abstraction away from the database. 

A repetitive task that arises when writing this kind of code is assigning database column values to 
member variables, in individual assignment statements. This feels like it should be unnecessary, 
especially when the columns and the corresponding variables have exactly the same names. In this 
section, we write a hack to automate this process. 

For concreteness, let's start with an actual database table. Following are the MySQL statements nec- 
essary to create a simple table and insert one row into it: 

mysql> create table book 

(id int not null primary key auto_i ncrement , 
author va rcha r ( 255 ) , title va rcha r ( 255 ) , 
publisher varchar(255)); 
mysql> insert into book (author, title, publisher) 

values ("Robert Zubrin", "The Case For Mars", 
"Touchstone" ) ; 

Because the i d column is auto-incremented, it will happen to have the value 1 for this first row. 
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The code in Listing 20-7 assumes a database called oop with the table created as above, and also 
that we have a file called dbconnect_vars that sets $host, $user, and $ p a s s appropriately for 
our particular MySQL setup. There is also little or no error checking (the code assumes the connec- 
tion works, that the row was retrieved successfully, and so on). The main point we want to highlight 
is the hack in the middle of the Book constructor. 



LISTING 20-7 



Matching variables and columns 

<?php 

include_once("dbconnect_vars.php"); 



class Book 
( 

public $ i d ; 



// variables corresponding to DB columns 
publ ic $author = " DBSET" ; 
public $title = "DBSET"; 
public $publisher = "DBSET"; 

public function construct ( $db_connecti on , $id) ( 

$this->id = lid; 

$ query = "select * from book " . 

"where id = $ i d " ; 
Sresult = mysql_query ( $query , $db_connecti on ) ; 
$db_row_a rray = 

my sql _f etch_a r ray ( $ resul t ) ; 
$cl ass_var_entri es = 

get_cl ass_vars ( get_cl ass($this)); 
while (Sentry = each( $cl ass_var_entri es ) ) ( 
$var_name = Sentry [' key '] ; 
$var_value = $entry[ ' val ue ' ] ; 
if ($var_value == "DBSET") { 
$thi s->$var_name = 

$db_row_array [$var_name] ; 



public function rename () ( 
$return„string = "B00K<BR>"; 
$cl ass_var_entri es = 

get_cl ass_vars ( get_cl ass($this)); 
while (Sentry = each( $cl ass_var_entri es ) ) ( 

$var_name = Sentry [' key '] ; 

$var_value = $thi s->$var_name ; 
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$return_stri ng .= 

"$var_name: $va r_va 1 ue<BR> " ; 

I 

return ( $ return_s t r i ng ) ; 

} 

} 

$connection = 

mysql _connect ( $host , $user, $pass) 
or die("Could not connect to DB"); 

mysql_sel ect_db( "oop" ) ; 

$book = new Book( $connecti on , 1); 

$book_string = $book->rename( ) ; 

?> 

<HTMLXHEADX/HEADXBODY> 
<?php echo $book_string ?> 
</BODYX/HTML> 



The database query returns all columns from the book table, and the values are indexed in the 
result array by the column names. The constructor then uses get_cl ass_va rs ( ) to discover all 
the variables that have been set in the object, tests them to see if they have been bound to the string 
" DBS ET " , and then sets those variables to the value of the column of the same name. 

The result is the output: 
BOOK 

Author: Robert Zubrin 
Title: The Case For Mars 
Publisher: Touchstone 

If we add fields to the database table definition, the only change we will need to make to 
Listing 20-7 is to add appropriately named variables to the class definition and initialize them to 
" D B S ET " . (We use this initialization to be clear about which variables should be overwritten, but 
also because we cannot retrieve the variables at all unless they have been initialized.) 

Example: Generalized test methods 

As a final introspection example, suppose that we are working on a large OOP project, with complex 
objects that need to maintain a lot of internal state. Testing is extremely important, because bugs 
will creep in and waste our time if we don't catch them early on. 

So let's adopt some testing conventions for this project. As one of them, let's agree that any class in 
our system can (optionally) define a member function called sel f Test ( ) . The point of this func- 
tion is to test the object instance it is called on to make sure the data in the object is valid and con- 
sistent across the instance. The s e 1 f Te s t ( ) function should always return FALSE if everything is 
okay and a diagnostic string if something is wrong. The coders of the objects agree that they will 
write these tests in such a way that a test can be applied at any time during execution. 
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If we agree on such a framework, we can write a general object tester. The tester simply calls 
sel f Test ( ) on any object it is pointed at, if such a method has been defined for that object. To 
make it easier to apply, we'll also make the object tester accept arrays of objects, and test each com- 
ponent object individually. Such an object tester is in Listing 20-8, along with some sample class 
definitions that have sel fTest( ) defined. 



LISTING 20-8 



ObjectTester 

class Name string { 
public $name; 
public SnameLength ; 
public Schecksum; 

public function const ruct ( $stri ng_i n ) 1 

$this->name = $string_in; 

$thi s ->namel_ength = strl en ( $stri ng_i n ) ; 

$thi s ->checksum = 

$this->computeChecksum($stri ng_i n ) ; 



public function setName ( $new_stri ng ) ( 
$this->name = $new_string; 
$thi s->namel_ength = strl en ( $new_stri ng ) ; 
$thi s->checksum = 

$ t h i s - > compu t eC hecks urn ( $new_st ri ng ) ; 



public function computeChecksum ($string) ( 
// not a good checksum in practice 
$sum = 0 ; 
for ($x = 0; 

$x < strlen($string); 
$x++) { 
$sum += ord($string[$x]); 

} 

return($sum % 100) ; 



public function selfTest () ( 

// returns FALSE if everything is OK 
if ( $thi s->namel_ength ! = 

st rl en ( $ t h i s ->name ) ) ( 
return("Name $this->name not of ". 

"length $thi s->namel_ength ! " ) ; 
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} 

e 1 s e i f 

( $thi s ->checksum != 

$this->computeChecksum($this->name)) { 
return( "Name $this->name fails checksum!"); 

} 

else ( 

return( FALSE) ; 

1 

} 

} 

class NonTesti ngObject ( 

} 

class ObjectTester ( 

public function ObjectTesterC ) ( 
// empty constructor 

1 

public function test ($thing) { 
if ( i s_ob ject ( $thi ng ) ) ( 

if ( methocLexi sts ( $thi ng , 'selfTest')) ( 
$thi s->handl eTest( 
cal l_user_f unc( 'selfTest', $thing) ) ; 

) 

} 

elseif ( i s_ar ray ( $thi ng ) ) ( 

foreach (Sthing as $component) ( 
$thi s ->test ( $component ) ; 

) 

1 

// ignore if not an array or object 

} 

public function handleTest (Iresult) 1 
if ($result) ( 

print(" Warning: Iresult"); 

} 



The Namestring object in Listing 20-8 has several pieces of data, which must be kept consistent 
with each other. Using the constructor to build an instance of Namestri ng keeps them consistent, 
as does changing the name with setName. Name string also defines sel f Test ( ) , which cross- 
checks the name, the length of the name, and a primitive checksum. 



344 



Introducing Object-Oriented PHP 



20 



Now let's see how to use the Object Tester class with some sample Namestring data: 



$object_list = array(); 

a rray_pus h ( $ob j ect_l i s t , new 

a rray_pus h ( $ob j ect_l i s t , new 

a rray_pus h ( $ob j ect_l i s t , new 

a r ray_push ( $ob j ect_l i s t , new 



Names tri ng( "Jordan" ) ) ; 
Namest ri ng (" Rodman ")) ; 
NonTesti ngOb j ect ) ; 
Namest ri ng (" Pi ppen ")) ; 



$tester = new Ob jectTester ( $ob j ect_l i st ) ; 

pri nt( "Runni ng test . . <BR>" ) ; 
$tester->test( $ob j ect_l i st ) ; 



pri nt ( " Changing name. .<BR>") ; 

$current_object = &$object_l i st[0] ; // note reference! 
$cu rrent_obj ect ->set Name ( "Mi chael " ) ; 
pri nt( "Runni ng test . . <BR> " ) ; 
$tester->test ( $object_l i st ) ; 



pri nt ( " Changi ng name . . <BR> " ) ; 

$current„object = &$object_l i st[l] ; // note reference! 
$current_object->name = "Jordan"; 



pri nt (" Runni ng test . . <BR> " ) ; 
$tester->test ( $object_l i st ) ; 

The results of running this code are: 

Runni ng test . . 
Changing name . . 
Runni ng test . . 
Changing name . . 
Runni ng test . . 

Warning: Name Jordan fails checksum! 



This warning resulted because we messed with the object's data directly the second time, rather 
than using the approved method for changing the name. 

We've used toy self-testing classes here, but the basic approach extends easily to more complex 
classes. Among possible extensions is more interesting handling of the warning messages (and pos- 
sibly interrupting execution). Another extension would be to use introspection on member variables 
themselves, as well as array components, to find contained objects and test those. This would mean 
defining the test runner recursively so that a thing passes a sel f Test ( ) if (1) its own sel f Test ( ) 
method (if it exists) finds no problem, and (2) any components (member variables, array slots) also 
pass sel f Test ( ) . (Watch out for circularities though! If the tester is ever called on objects that 
mutually refer to each other, it would have to be rewritten to track the identities of previously seen 
objects and would only test each object once.) 
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Extended Example; HTML Forms 

All the OOP code you've seen so far in this chapter has been fairly short, so in this chapter we pres- 
ent an extended piece of code for your enjoyment, shown in Listing 20-9. 

The point of this class is to semiautomate the production of HTML forms, which one of your authors 
has always found to be a bit of a pain to generate. The top-level class represents a form, while other 
classes represent inputs, text areas, and hidden variables (just the ones that your author uses most 
frequently). The idea is that you can make a form by adding input fields to an existing object and 
display the form upon request. The resulting form will be not be especially pretty (every element 
is displayed sequentially down the left-hand side of the page), but it's good enough for situations 
where, say, you want to enter some information into your own database yourself. 



LISTING 20-9 



form_printer.php 

<?php 

// The form class itself — 

cl ass Html Form ( 

// suitable for generating quick & dirtyforms 

public $acti onTarget ; // path to receiving page 
private SinputForms; // array of Html FormI nput 
public ShiddenVar tables; // associative name/val 

// CONSTRUCTOR 

public function cons t ruct ( $act i on_ta rget ) ( 

$thi s->acti onTarget = $acti on_ta rget ; 
$thi s->i nputForms = array(); 
$thi s - > hi ddenVari abl es = arrayO; 



// PUBLIC METHODS 
public function rename () I 
$return„stri ng = " " ; 
$return_stri ng .= 

"<F0RM METH0D=\"P0ST\" ". 
"ACTION=\"$thi s->actionTarget\">\n" ; 



$return_ 


_s t r i 


ng 


.= $thi s->i nputFormsStri ng( ) ; 


$return_ 


_s t r i 


ng 


. = $this->hiddenVariablesString( ) 


$return_ 


_s t r i 


ng 


.= "<BR>\n"; 


$return_ 


_s t r i 


ng 


.= $thi s->submi tButtonStri ng( ) ; 


$return_ 


_s t r i 


n 9 


.= "</F0RM>"; 
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return ( $ return_st ri ng ) ; 

} 

// adding elements to form 

public function addlnputForm ( $i nput_f orm) { 
if ( ! i sSet ( $ i nput_f orm ) 

! i s_ob j ect ( $ i nput_f orm ) | 
! i s_subcl ass_of ( $ i nput_f orm , 
' html f ormi nput ' ) ) ( 
di e( "Argument to Html Form :: add Input Form ". 
"must be instance of Html Formlnput . " . 

Given argument is of class " . 
get_cl ass ( $ i nput_f orm ) ) ; 

) 

else ( 

array_push( $this->inputForms, $i nput_f orm) ; 

) 

} 

public function add I nputButton ( $i nput_button ) 1 
if ( ! i sSet ( $ i nput_button ) | 
! i sOb j ect ( $i nput_button ) | 
! i s_a ( $i nput_button , 'HtmllnputButton'))) 
di e( "Argument to Html Form :: add InputButton ". 
"must be instance of HtmllnputButton"); 

1 

else ( 

a r ray_push ( $this->inputButtons, $ i nput_button ) ; 

) 

) 

public function addHi ddenVari abl e ($name, $value) ( 
if ( !isSet($value)) { 

di e (" Html Form :: addHi ddenVa ri abl e requires ". 
"two arguments (name and value)"); 

) 

else ( 

$this->hiddenVariables[$name] = lvalue; 

) 



public function i nputFormsStri ng () ( 
$return_stri ng = " " ; 
$form_array = $thi s->i nputForms ; 
foreach ($form_array as $input„form) 1 
$return_stri ng .= 

"<B>$i nput_f orm->headi ng</B>" ; 
if ( $thi s->headi ngEl ementBreak( ) ) { 
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$return„stri ng .= "<BR>"; 

) 

$return_stri ng .= $i nput_form->rename( ) ; 
$return_stri ng .= "<BR>\n"; 

} 

return ( $ return_s t r i ng ) ; 

} 

public function hi ddenVa ri abl esSt ri ng () { 
$return_stri ng = " " ; 
while ( $hi dden_va r = 

each($this->hiddenVariables)) { 
$var_name = $ hi dden_va r [ ' key ' ] ; 
$var_value = $hi dden„var[ ' val ue ' ] ; 
$return_stri ng .= 

"<INPUT TYPE=H I DDEN " . 
"NAME=$var_name ". 
"VALUE=$var_val ue >"; 
$return_stri ng .= "\n"; 

) 

return ( $ return_s t r i ng ) ; 

1 

public function headi ngEl ementBrea k () { 

// override to disable breaks after headings, 
// or to do more complicate layout 
return(TRUE) ; 

1 

public function submi tButtonStri ng () { 
$return_string = " < I N PUT TYPE=Submit " . 

" VALUE=Submit >\n"; 
return ( $return_stri ng ) ; 

} 

} 

// Classes for parts of a form 

abstract class Html Formlnput { 

public $name; // The variable name for form submission 
public Sheading; // The visible label on form 

function construct!) ( 

die("Class Html Formlnput intended only " . 
"to be subcl assed" ) ; 

1 

function rename () j 

di e( "Subcl ass of Html Formlnput missing " . 
"definition of rename()"); 

} 
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class Html FormSel ect extends Html Formlnput 
{ 

public $_val ueArray = array(); 
public $_sel ectedVal ue ; 



public function construct ($name, Sheading, 

$ v a 1 ue_array , 
$sel ected_val ue=NULL) 1 
if ( ! i sSet ( $ val ue_a rray ) ) I 

di e (" Html FormSel ect needs a minimum of two " . 
"arguments: a name, and value array"); 

} 

elseif (! i s_a rray ( $val ue_a rray ) ) { 

die("Third argument to Html FormSel ect( ) " . 
"should be array where keys are values ". 
"submitted, and values are display values"); 

) 

else ( 

// actual initialization 

$this->name = $name; 

$this->heading = Sheading; 

$thi s->_val ueArray = $val ue_array ; 

$thi s->_sel ected_val ue = $sel ected_val ue ; 

) 

} 



public function rename () ( 
$return„stri ng = " " ; 
$return_stri ng .= 

" <SELECT NAME=\"$this->name\">" ; 
while ($var_entry = 

each ( $thi s ->_val ueArray ) ) ( 
$submi t_val ue = $var_entry [ ' key ' ] ; 
$di spl ay_val ue = $va r_entry [ ' val ue ' ] ; 
if ( $submi t_val ue == $thi s->_sel ected„val ue) ( 
$return_stri ng .= 

"<0PTI0N VALUE=${submit_value) SELECTED >"; 

} 

else ( 

$return_stri ng .= "<0PTI0N VALUE=$ { submi t_val ue ) > " ; 

I 

$return_stri ng .= $di spl ay_val ue ; 

) 

$return_stri ng .= 

"</SELECT>" ; 
return($return_string) ; 

1 

} 



class Html FormText extends Html Formlnput 
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{ 



public $ i ni t i al _va 1 ue ; 

public function construct ($name, 

Sheading, 

$ i ni t i al _va 1 ue=" " ) 

{ 

// Initialization of member vars 
if ( ! i sSet($name) | | 

!isSet($heading)) { 
di e( "Html FormText constructor needs " . 

"at least two arguments (name, heading)"); 

} 

$this->name = $name; // name defined in parent 
$this->heading = Sheading; // defined in parent 
$thi s->i ni ti al_val ue = $i n i ti al_val ue ; 

} 

public function rename () ( 
$return_stri ng = " " ; 

$return_string .= "<INPUT TYPE=TEXT "; 
$return_stri ng .= "NAME=\"$thi s->name\" "; 
$return_stri ng .= 

"VALUE=\"$this->initial_val ue\" " ; 
$return_stri ng .= " >"; 
return ( $return_stri ng ) ; 



class Html FormTextArea extends Html FormI nput ( 
public $ i ni t i al _va 1 ue ; 
public $ rows ; 
public $cols; 
publ i c SwrapType ; 

public function construct ($name, 

Sheading, 
// optional args: 
$i ni ti al_val ue=" " , 
$rows=l, $cols=60, 
$wrapType="VIRTUAL" ) 

{ 

// Initialization of member vars 
if (!isSet($name)) { 

di e( "Html FormTextArea constructor needs " . 
"at least two arguments (name, heading)"); 

1 

$this->name = $name; // name defined in parent 

$thi s->headi ng = Sheading; // name defined in parent 

$thi s->i ni ti al_val ue = $i n i ti al_val ue ; 
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$this->rows = $rows; 
$this->cols = $cols; 
$thi s->wrapType = SwrapType; 



public function rename () 



$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
$return_stri ng 
return ( $ return. 



"<TEXTAREA " ; 
"NAME=\"$this->name\" "; 
"R0WS=$thi s->rows "; 
"C0LS=$thi s->col s "; 
"WRAP=$thi s->wrapType "; 
$this->additionalAttributes( 
" > " ; 

$ t h i s - > i n i t i a 1 _v a 1 u e ; 
"</TEXTAREA>" ; 
string) ; 



public function add i ti onal Attri butes () ( 
// OVERRIDE THIS to return a string with 
// TextArea attributes other than 
// NAME, ROWS, COLS, and WRAP 
r e t u r n ( " " ) ; 

1 

1 

?> 



The basic design for all these objects includes a constructor function with default arguments and 
a ren a me ( ) method that returns HTML for the form or piece thereof. Forms store pieces of input 
(which might conceivably be reordered or laid out by a more sophisticated version), and recursively 
call rename ( ) on these pieces. The HTML form elements that are supported are: TEXTAREA, TEXT, 
and SELECT. 

Here is an example of calling this code to generate a simple form page: 

<HTMLXHEADX/HEADXBODY> 
<?php includet "form_pri nter . php" ) ; 
$my_form = new Html Form( $PHP_SELF) ; 
$my_f orm->addInputForm( 

new Html FormText( "f i rstname" , 
" First Name " ) ) ; 

$my_f orm->addInputForm( 

new Html FormText( "1 astname" , 
" Last Name" ) ) ; 

$my_form->addInputForm( 

new Html FormSel ect ( 
"age" , 
"Age" , 
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array(0 => "0 - 9" , 

1 => "10 - 19", 

2 => "20 - 29", 

3 => " Seni or ci ti zen " ) , 

2) ) ; 

$my_f orm->add Input Form( 

new Html FormTextArea ( 
"feedback" , 

"What ' s on your mi nd? " , 
"[Please fill in your own personal rant]", 

5)) ; 

pri nt( $my_f orm-> rename ( ) ) ; 
?> 

</B0DY> 
</HTML> 



Much of the form-producing code is straightforward and is concerned with churning out various 
kinds of HTML syntax. There are two interesting things to notice from the point of view of OOP-in- 
PHP, however. 

The first is that the Html Formlnput classis designated abstract. That is , it exists not to be instan- 
tiated but only to be inherited from. The second point of interest is that the Html Form class has an 
array that is intended to hold Html Formlnput objects. Of course, because PHP is loosely typed, we 
cannot enforce that in any way at compile time, although the manufacturer-approved way to insert 
new forms (addInputForm( )) does some type-checking on insertion. If users of this class rely only 
on this method, we can be assured that everything that ends up in that array will be an instance of 
Html Formlnput (or subclass thereof) and so should be a well-behaved form element when display 
time comes around. The private designation guarantees that the array cannot be manipulated 
from outside the class at runtime. 



Gotchas and Troubleshooting 

In the spirit of Chapter 10, we offer in the following sections the top-two most likely symptoms of 
problematic OOP code, along with the most likely cause. 

Symptom: Member variable has no value in 
member function 

This could have many causes, of course, but the most common is simply a confusion about the right 
way to refer to member variables. The syntax is: 

$thi s->member_name 
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If, instead, your function simply refers to $member_name, that will usually be an unbound variable 
and, at any rate, will never succeed in referring to the member variable. Similarly, if your function 
refers to $thi s ->$member_name, you are asking for the field named by the string in the variable 
$member_name (which is probably unbound). 

Symptom: Parse error, expecting T_VARI ABLE . . . 

There are of course many ways to munge a class definition so that PHP will complain when it tries to 
parse it. One of the most common errors again has to do with placement of those $ symbols. A class 
declaration like the following: 

class MyClass ( 

publ ic my^var; // WRONG 

1 

inevitably gives you a parse error of some sort because the syntax requires a $ before my_va r. 



OOP Style in PHP 

The topic of OOP programming style is a huge one (because it includes OOP design!) and is well 
beyond the scope of this book. In the spirit of Chapter 32, however, we offer in the following sec- 
tions some brief notes on writing readable, maintainable PHP OOP code. 

Naming conventions 

In this section, we simply pass along the parts of the PEAR coding style that pertain to objects. 

p 'rj cj'c c J r { p ^ * : ° r more information on the PEAR project and the PEAR coding style, see Appendix E or 
J -" C -' r -' the PEAR website (at http://pear.php.net). 

PEAR recommends that class names begin with an uppercase letter and (if in a PEAR-approved 
directory hierarchy of packages) have that inclusion path in the class name, separated by under- 
scores. So your class that counts words, and that belongs to a PEAR package called TextUti 1 s, 
might be called TextUti 1 s_WordCounter. If building large OOP packages, you may want to emu- 
late this underscore convention with your own package names; otherwise, you can simply give your 
classes names like WordCounter. 

Member variables and member function names should have their first real letter be lowercase and 
have word boundaries be delineated by capitalization. In addition, names that are intended to be 
private to the class (that is, they are used only within the class, and not by outside code) should 
start with an underscore. So the variable in your WordCounter class that holds the count of words 
might be called wordCount (if intended to be messed with from the outside) or _wordCount (if it is 
intended to be private to the class). 
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Accessor functions 

Another style of documenting your intent about use of internal variables is to have your variables 
marked as private, in general, and provide "getter" and "setter" functions to outside callers. For 
example, we might define a class like this: 

class Customer 
{ 

private var _name; 

private var _credi tCa rdNumber ; 

pri vate var _rati ng ; 

f uncti on getName ( ) 

return ( $thi s->_name ) ; 

f uncti on getRati ng ( ) 

return($this->_rating) ; 

function setRat i ng ( $rati ng ) 

$thi s->_rati ng = $ rating; 
[ . . . more f uncti ons ] 

} 

This class definition has three private variables: one (_c red i tCa rdN umbe r) that should neither be 
set nor retrieved from outside code, another (_name) that outside code should be able to retrieve but 
not set, and a third (_rati ng) that outside code should feel free to both get and set. 

Although PHP class syntax lets you interleave variables with function definitions, it's a good idea, in 
general, to organize your code so that similar items with similar usage intent are located together in 
the class definition. For example, you might develop the habit of laying out class functions like this: 

class my Class 
( 

// Public variables: 

// Private variables 

// Constructor 

// Public functions 

// Private functions 

1 
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Designing for inheritance 

The question of exactly how to design a class hierarchy is, as we've said, a vast area of study unto 
itself, and we're not about to try to contribute to it here. Just as a stylistic matter, though, it's worth 
thinking about whether you intend your class to be inherited from, and then try to indicate your 
decision, either with comments or in the structure of the definition. 

For example, you may intend that your class should never breed, in which case you might just 
indicate that in comments, and then stop worrying about inheritance issues. (There is currently 
no way in PHP to enforce that a class cannot be inherited from.) At the other end of the spectrum, 
you might have all or part of your class intended only for inheritance. You can indicate this in 
comments, or you can use the trick we used in the definition of Html Formlnput in Listing 20-9: 
Provide methods that die informatively when called directly in the base class. Finally, of course, you 
may have some methods that can be called directly in the base class but are especially intended for 
overriding. You may want to group these "hook" methods together in a clearly marked section of 
your class definition, so that the later writer of a derived class can quickly figure out what options 
are available for specializing the class's behavior. (Remember that the clueless coder of the future 
that you are helping may well be yourself.) 



Summary 

PHP provides the basics to support object-oriented programming. Among other things, the OOP 
syntax in PHP allows for programmer-defined classes with member variables and member data and 
offers single inheritance, constructor functions, object serialization, and functions for introspection. 
Nothing in PHP requires that you write in an object-oriented style, but if you prefer that style you 
can write almost all your code that way. PHP was not originally intended to be an object-oriented 
language, and developers with OOP experience will miss some aspects of more mature OOP lan- 
guages. On the other hand, the OOP extension is usable, fairly mature, pretty stable, and widely 
used. It provides an extra layer of organization that can be helpful when maintaining complex code 
and offers a nice way to package code for distribution and reuse. 
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In Chapter 8 we introduced you to arrays, their uses, and some handy 
functions for working with them. In some subsequent chapters, we saw 
how PHP returns many of its results as arrays, particular when work- 
ing with database function sets. This chapter will look at some of the more 
advanced functions for working with PHP arrays. 



Transformations of Arrays 

PHP offers a host of functions for manipulating your data once you have it 
nicely stored in an array. What the functions in this section have in com- 
mon is that they take your array, do something with it, and return the 
results in another array. (We will defer the array-sorting functions until a 
later section.) 



Not covered in this chapter are expl ode ( ) and i mpl ode ( ), 
which convert strings into arrays and vice versa. We cover these 
very handy functions in Chapter 22. 



In Chapter 8, we incrementally developed a function to print out the 
entire contents of an array, and in this section we will use the last of these 



IN THIS CHAPTER 



Transformations of arrays 

Stacks and queues 

Translating between variables 
and arrays 

Sorting 
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(pri nt_key s_and_val ues_each ( )) to show the arrays that are being returned in examples. We'll 
list this function again here, in a more generic form: 

function pri nt_key s_and_val ues_each ( $a r ray_to_test ) 
( // reliably prints everything in array 
reset ( $a rray_to_test ) ; 

while ($array_cell = each ( $a r ray_to_test ) ) 

{ 

$current_val ue = $array_cel 1 [ ' val ue ' ] ; 
$current_key = $array_cel 1 1 ' key ' ] ; 

print("Key: $current_key ; Value: $current_val ue<BR>" ) ; 

) 

} 

Retrieving keys and values 

The array_keys( ) function returns the keys of its input array in the form of a new array where the 
keys are the stored values. The keys of the new array are the usual automatically incremented inte- 
gers, starting from 0 . The array_val ues( ) function does exactly the same thing, except the stored 
values are the values from the original array. If we start with an array like the following: 

$pi zza_requests = a r ray ( ' Al i ce ' => 'pepperoni', 

' Bob ' => ' mushrooms ' , 
' Carl ' => ' sausage ' , 
'Dennis' => 'mushrooms'); 

and then we print the arrays resulting from calls to the these two functions: 
print("Array keys:<BR>"); 

pri nt„keys_and_val ues_each ( a r ray_key s ( $pi zza_requests ) ) ; 
print("Array val ues : <BR>" ) ; 

pri nt_key s_and_val ues_each ( a r ray_va 1 ues($pizza_requests)); 
we get output like this: 



Array 


keys : 




Key: 


0 


Value: 


Al i ce 


Key: 


1 


Value: 


Bob 


Key: 


2 


Val ue: 


Carl 


Key: 


3 


Value: 


Dennis 


Array 


val ues : 




Key: 


0 


Value: 


pepperoni 


Key: 


1 


Value: 


mushrooms 


Key: 


2 


Value: 


sausage 


Key: 


3 


Value: 


mushrooms 



The second of these (array_val ues( )) may seem uninteresting because we have essentially taken 
our old array and produced a new one with the keys renamed to successive numbers. 
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We can do something slightly more useful (and more helpful for ordering) with the function a r r ay_ 
c o u n t_v a 1 u e s ( ) . This takes an array and returns a new array, where the old values are now the 
new keys and the new values are the number of times each old value occurs in the original array. 

pri nt_keys_and_val ues_each ( 

array_count_val ues($pizza_requests)) ; 

gives us: 

Key: pepperoni ; Value: 1 
Key: mushrooms; Value: 2 
Key: sausage; Value: 1 

Flipping, reversing, and shuffling 

A function that is even more odd is a rray_f 1 i p ( ) , which changes the keys of an array into the val- 
ues, and vice versa. For example: 

pri nt_keys_and_val ues_each ( a rray_f 1 i p ( $pi zza_requests ) ) ; 
gives us: 

Key: pepperoni; Value: Alice 

Key: mushrooms; Value: Dennis // what happened to Bob? 
Key: sausage; Value Carl 

Notice that, although array keys are guaranteed to be unique, array values are not — because of this, 
any duplicate values in the original array become the same key in the new array. Only one of the 
original keys will survive to become the corresponding new value. 

Reversing an array is more simple: a rray_reverse ( ) returns a new array with the key/value pairs 
in reverse order. So, with the usual printing test: 

pri nt_keys_and_val ues_each ( array_reverse($pi zza_requests ) ) ; 
we get the result: 

Key: Dennis; Value: mushrooms 

Key: Carl; Value: sausage 

Key: Bob; Value: mushrooms 

Key: Alice; Value: pepperoni 

In this case, although the internal order has been reversed, all the key/value pairs end up being 
the same. However, this function (like several other PHP array functions) treats integer keys some- 
what special. It assumes that the ordering of integer keys on those key/value pairs should also 
be reversed for the later use of code that pays attention to the ordering of keys, rather than using 
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the internal linked-list ordering. So, array_reverse( ) swaps integer keys to make the new key 
ordering match the internal list. Dennis, in other words, is now actually at position 0. 

If you need some extra randomness in your life, the s h u f f 1 e ( ) function can give it to you — 
s h u f f 1 e ( ) takes an array argument and pseudo-randomizes the order of the elements in the array. 
It uses r a n d ( ) , a function that generates successive pseudo-random numbers. Before you use 
s h u f f 1 e ( ) , you need to have seeded the random-number generator with a call to srand( ). (See 
the discussion of random-number generation in Chapter 9.) A reasonable calling sequence looks 
like this: 

s rand ( ( doubl e )mi croti me ( ) * 1000000); // for random # gen 
shuffle($pi zza_requests ) ; 

pri nt_keys_and_val ues_each ( a r ray_f 1 i p( $pi zza_requests ) ) ; 
which might give us output like: 

Key: Carl; Value: sausage 

Key: Bob; Value: mushrooms 

Key: Dennis; Value: mushrooms 

Key: Alice; Value: pepperoni 

r- , * | ^"jsj- ' Unlike many of the array functions in this chapter, shuff 1 e( ) is destructive, meaning 
iBBm&mAmm^t that it operates directly on its array argument and changes it, rather than returning a 
newly created array. (Functions that return a new thing without disturbing their arguments might be 
called constructive, or just nondestructive.) Among other things, this means that the correct way to call 
the shuffle function is not: 

$my_new_a rray = shuf f 1 e ( $my_ol d_a rray ) ; //WRONG! 

especially because the shuf f 1 e ( ) function does not return a value. Instead, the right call is: 

shuf fl e ( $my_a rray ) ; // change the array itself 



Merging, padding, slicing, and splicing 

If we want to combine two arrays for a more complete list, the function to use is array_merge( ). 
This function takes two or more arrays as arguments and returns a renumbered new array that is the 
second array tacked onto the end of the first. If we create a new array containing some additional 
pizza requests like this: 

$more_pi zza„requests = array('Ted' => 'anchovies', 

'MrWilson' = > 'pineapple', 
' Dagwood ' => ' ham ' ) ; 

then we can use a rray merge();as: 

$al l_requests = array_merge( $pi zza_requests , $more_requests ) ; 
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and then use our handy array inspecting function: 

pri nt_keys_and_val ues_each ( $all_requests); 



We should see: 



Key: Alice; Value: pepperoni 

Key: Bob; Value: mushrooms 

Key: Carl; Value: sausage 

Key: Dennis; Value: mushrooms 

Key: Ted; Value: anchovies 

Key: MrWilson; Value: pineapple 

Key: Dagwood; Value: ham 



The a r r ay_p a d ( ) function is used to create some leading or following key/value pairs increas- 
ing the size of an array. It takes an input array as its first argument, then a number of elements to 
increase the array to, and then a value to assign to the added elements. A positive integer in the sec- 
ond argument will pad the end of the array; a negative integer will pad the beginning. If the second 
argument is smaller than the size of the array, no padding is performed. 

$requests = a r ray_pad ( $pi zza_requests , 10, 'mushrooms') 
//do we have any mushroom fans in the audience tonight? 



With our function, we'd get: 

Key: Alice; Value: pepperoni 

Key: Bob; Value: mushrooms 

Key: Carl; Value: sausage 

Key: Dennis; Value: mushrooms 



Key 


0 


Value: 


mus h rooms 


Key 


1 


Value: 


mushrooms 


Key 


2 


Value: 


mushrooms 


Key 


3 


Value: 


mushrooms 


Key 


4 


Value: 


mushrooms 


Key 


5 


Value: 


mushrooms 



If we make the second argument negative, the new elements appear at the beginning of the array. 
Note that the automatically assigned keys start at 0, even though they are in the fifth position. 

Somewhat more complicated are the array_sl i ce( ) and array_spl i ce( ) functions. The first of 
these returns a subset of an input array by accepting an offset and a length as its second and third 
arguments, respectively: 

$subset = a r ray_sl i ce ( $pi zza_requests , 1, 2); 
// returns mushrooms and sausage 
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The a r ray_spl i ce ( ) function is similar, but it accepts a fourth argument, which can be an array 
of any length, to splice into the input array, again returning an all new array: 

$super_set = a rray_spl i ce ( $pi zza_requests , 2, 0, 
$more_requests ) ; 

which will return an array like: 

Key: Alice; Value: pepperoni 

Key: Bob; Value: mushrooms 

Key: Ted; Value: anchovies 

Key: MrWilson; Value: pineapple 

Key: Dagwood; Value: ham 

Key: Carl; Value: sausage 

Key: Dennis; Value: mushrooms 

These array-manipulating functions are summarized in Table 21-1. 



TABLE 21-1 



Array Transformation Functions 


Function 


Behavior 


a rray_ 
keys ( ) 


Takes a single array argument and returns a new array where the new values are the 
keys of the input array, and the new keys are the integers incremented from zero. 


a rray_ 
val ues ( ) 


Takes a single array argument and returns a new array where the new values are the 
original values of the input array, and the new keys are the integers incremented from zero. 


a rray_ 
count_ 
val ues ( ) 


Takes a single array argument and returns a new array where the new keys are the old 
array's values, and the new values are a count of how many times that original value 
occurred in the input array. 


a rray_ 
flipO 


Takes a single array argument and changes that array so that the keys are now the values 
and vice versa. 


a rray__ 
reverse( ) 


Takes a single array argument and changes the internal ordering of the key/value pairs to 
reverse order. Numerical keys will also be renumbered. 


shuffleO 


Takes a single array argument and randomizes the internal ordering of key/value pairs. 
Also renumbers integer keys to match the new ordering. This function itself uses the 
random-number generator rand (), so s rand ( ) must be called to seed the generator 
before the call to shuff 1 e( ). 


a rray_ 
merge ( ) 


Takes two array arguments, merges them, and returns the new array, which has (in 
order) the first array's elements and then the second array's elements. {Note: This is most 
useful for arrays that are being used for simple linked lists rather than for their associative 
keys, because keys that appear in both arrays will have one of the values overwritten. 
Also, numerical keys will be renumbered from 0 to reflect the new ordering.) 
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Function Behavior 

a rray_pad ( ) Takes three arguments: an input array, a pad size, and a value to pad with. Returns a 
new array that is "padded" by the following rules: If the pad size is greater than the 
length of the input array, the array is lengthened with the pad value to the pad size, as 
though by successive assignments like $my_a r ray [ ] = $pad_val ue. A negative 
pad size will act the same way with the absolute value of that pad size, except that 
the padding will occur at the beginning of the array rather than the end. If the array is 
already longer than the (absolute value of) the pad size, the function has no effect. 

Takes three arguments: an input array, an integer offset, and an (optional) integer length. 
Returns a new array that is a "slice" of the old one — a subsequence of its list of key/ 
value pairs. The starting and stopping points of the slice are determined by the offset 
and length. A positive offset means that the starting point is that number of elements 
after the beginning; a negative offset means that it is that many elements before the end. 
The optional length argument specifies how long the resulting slice is (if positive) or how 
many elements before the end it should stop (if negative). If the length argument is not 
present, the slice continues to the end of the array. 

Removes a chunk (or a slice) of an array and replaces it with the contents of another 
array. Takes four arguments: an input array, an offset, an optional integer length, and an 
optional replacement array. Returns a new array containing the slice that was removed 
from the input array. 

The rules for using the offset and length arguments to determine the slice that is 
removed are the same as in the previous a r ray_s 1 i ce ( ) function. 

If no replacement array is supplied, this function simply (destructively) removes a slice 
of the input array and returns it. If there is a replacement array, the elements of that array 
are inserted in place of the removed slice. 



Stacks and Queues 

Stacks and queues are abstract data structures, frequently used in computer science, that enforce 
a certain kind of access discipline on the objects they contain, without necessarily committing to 
what those objects are. PHP arrays are well suited to imitating other kinds of data structures, and 
the loose typing of PHP array elements makes it easy for them to imitate stacks and queues. PHP 
provides some array functions specifically for this purpose — if you use them exclusively, you can 
forget that arrays are involved at all. 

A stack is a container that stores values and supports last-in-first-out (LIFO) behavior. This means 
that the stack maintains an order on the values you store, and the only way you can get a value back 
is by retrieving (and removing) the most recently stored value. The usual analogy is a stack of caf- 
eteria trays in one of those dispensers that keeps the top tray at a constant level. You can push new 
trays down on top of the old ones, and you can take trays off the top, but you can't grab an older tray 
without taking the newer ones first. The act of adding into the stack is called pushing a value onto 



array_ 
s 1 i ce ( ) 



a rray_ 
spl i ce( ) 
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the stack, whereas the act of taking off the top is called popping the stack. Another analogy is the way 
some web browsers store the pages you have visited for use by the Back button; visiting a new page 
pushes a new URL onto that stack, and using the Back button pops the stack. 

A queue is similar to a stack, but its behavior is first in, first out (FIFO). The usual analogy here is 
what the British call a queue and what Americans call a line, where people line up in order to wait for 
something. The rule is that whoever has been in the queue the longest is the next to be served. 

The stack functions are a r ray„push ( ) and ar ray_pop ( ) . The a rray_push ( ) function takes an 
initial array argument and then any number of elements to push onto the stack. The elements will 
be inserted at the end of the array, in order from left to right. The a r ray_pop ( ) function takes such 
an array and removes the element at the end, returning it. Take the following fragment: 

$my_stack = array(); // needed--array_push( ) will not create 
a rray_push ( $my_stack , "the first", "the middle"); 
array_push( $my_stack , "the last"); 
while (Spopped = array_pop( $my__stack) ) 

pri nt (" Popped the stack and got: $popped<BR> " ) ; 

This will produce the browser output: 

Popped the stack and got: the last 
Popped the stack and got: the middle 
Popped the stack and got: the first 

PHP also offers functions that behave exactly the same way as array _push( ) and a r r a y_p o p ( ), 
except that they work at the other end, adding to and removing from the beginning of the array. The 
a rray_unshi f t ( ) function is analogous to a r ray_push ( ) , and a r ray_shi f t ( ) is like a rray_ 
pop ( ) . If you choose one function from column A and one from column B, you can get the behavior 
of a queue. For example, we can rewrite our previous example to push into the beginning of the 
array (using a rray_uns hi f t ( )) and pop from the end (using ar ray_pop ( ) , as before): 

$my_queue = arrayO;// needed--array_unshi ft( ) will not create 
array_unshi ft( $my_queue , "the first"); 
a rray_unshi ft ( $my_queue , " the middle"); 
array_unshift($my_queue, "the last"); 
while (Spopped = a rray_pop ( $my_queue ) ) 

pri nt (" Popped the queue and got: $popped<BR> " ) ; 

It produces the output: 

Popped the queue and got: the first 
Popped the queue and got: the middle 
Popped the queue and got: the last 



364 



Advanced Array Functions 



21 




The a rray_unshi f t ( ) and ar ray_shi ft ( ) functions are somewhat different from 
a r r a y„p u s h ( ) and array _pop() in that the former do some renumbering of the array 



indices if the indices are integers. The idea is that some people may be relying on the numerical indi- 
ces to order the array contents, so using a rray„unshi f t ( ) to insert a new element at the beginning 
should assign an index of 0 to the new element, and renumber those above. Similarly, popping an ele- 
ment from the beginning with a r ray_s h i f t ( ) causes integral indices of other elements to be reduced. 
(This is not an issue with a r ray_push and array_pop, because changes are at the end, and no renum- 
bering is needed.) If you are using string indices exclusively, this renumbering has no effect. This is a 
general pattern with PHP array functions: Some of them treat integer indices like any other associative 
indexes, whereas others assume that integers imply order, and redo them if the order has changed. 

The stack and queue functions are summarized in Table 21-2. 



TABLE 21-2 



Stack and Queue Functions 


Function 


Arguments 


Side Effect 


Returns 


array_ 
push( ) 


An initial array 
argument, then any 
number of values to be 
pushed onto the stack. 


Modifies the array by 
adding the elements in 
order to the end of the 
array. 


Returns the number of 
elements in the array after 
the push. 


array_pop( ) 


A single array argument. 


Removes the element at 
the end of the array. 


Returns the last (removed) 
value, or a false value if the 
array is empty. 


array_ 
unshi ft( ) 


An initial array 
argument, then any 
number of values to be 
pushed onto the front of 
the array. 


Modifies the array by 
adding the successive 
elements to the 
beginning. (The last 
argument will be at the 
beginning of the array.) 


Returns the number of 
elements in the array after 
the new elements are 
added. 


a rray_ 
shiftO 


A single array argument. 


Removes the element 
at the beginning of the 
array. 


Returns the first (removed) 
value or a false value if the 
array is empty. 



Translating between Variables and Arrays 

PHP offers a couple of unusual functions for mapping between the name/value pairs of regular vari- 
able bindings and the key/value pairs of an array. The compa ct ( ) function translates from variable 
bindings to an array, and the extract ( ) function goes in the opposite direction. These are summa- 
rized briefly in Table 21-3. 
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TABLE 21-3 



Array/Variable-Binding Functions 

Function Behavior 

compact ( ) Takes a specified set of strings, looks up bound variables (if any) in the current 

environment that are named by those strings, and returns an array where the keys are 
the variable names, and the values are the corresponding values of those variables. 

This function takes any number of arguments, each of which is either a string or an 
array that contains strings at some level of index depth. The entire set of strings that are 
included in the argument(s) is used as the candidate set of variable names. Strings that 
do not correspond to bound variables are ignored. 

extract! ) Takes an array (plus two optional arguments explained in the next paragraph) and 

imports the key/value pairs into the current variable-binding context. The array keys 
become the variable names, and the corresponding array values become the values 
of the variables. Any keys that do not correspond to a legal variable name will not 
produce an assignment. 

The optional arguments are an integer (intended to receive one of a small set of 
constants) and a prefix string. The point of these arguments is to specify what should 
happen in the case of a collision between the name of an existing variable and one 
that would be created from an array key. 

The intended possible constants for the optional integer arguments include (1) EXTR_ 
OVERWRITE, (2) EXTR_SKIP, (3) EXTR_PREFIX_SAME, and (4) EXTR_PREFIX_ 
ALL. The corresponding behaviors are (1) go ahead and overwrite existing variables, 
(2) skip any new assignments that would require overwriting, (3) use the optional 
prefix string to distinguish the new variable from the old one, or (4) prefix all the 
new variables with the string. For example, extract(array( ' my_va r ' => 4 ) , 
EXTR_PREFI X„SAME , 'diff_' ) ; would cause $my_var to be 4 if $my^var 
were not already bound; otherwise, it would assign the value 4 to $di f f_my_va r. 
Other constants exist, though are less commonly used. See http: / /php.net/ 
extract for more information. 



Sorting 

Finally, PHP offers a host of functions for sorting arrays. As you saw earlier, a tension sometimes 
arises between respecting the key/value associations in an array and treating numerical keys as 
ordering info that should be changed when the order changes. Luckily, PHP offers variants of the 
sorting functions for each of these behaviors and also allows sorting in ascending or descending 
order and by user-supplied ordering functions. The function names are terse, but each letter (other 
than the sort part) has its meaning. The decoder ring is something like: 

■ An initial a means that the function sorts by value but maintains the association between 
key/value pairs the way it was. 
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■ An initial k means that it sorts by key but maintains the key/value associations. 

■ A lack of that initial a or k means that it sorts by value but doesn't maintain the key/value 
association. In particular, numerical keys will be renumbered to reflect the new ordering. 

■ An r before the sort means that the sorting order will be reversed. 

■ An initial u means that a second argument is expected: the name of a user-defined function 
that specifies the ordering of any two elements that are being sorted. (See the description 
in Table 21-4.) 



TABLE 21-4 



Array Sorting Functions 


Function 


Behavior 


a s o r t ( ) 


Takes a single array argument. Sorts the key/value pairs by value but keeps the key/value 
mapping the same. Good for associative arrays. 
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ksort ( ) 


Takes a single array argument. Sorts the key/value pairs by key but maintain the key /value 
associations the same. 


krsort( ) 


Same as kso rt ( ), but sorts in descending order. 


sort( ) 


Takes a single array argument. Sorts the key/value pairs of an array by their values. Keys 
may be renumbered to reflect the new ordering of the values. 


rsort ( ) 


Same as s o r t ( ) , but sorts in descending order. 


uasort( ) 


Sorts key/value pairs by value using a comparison function. Similar to a so rt ( ), except 
the actual ordering of the values is determined by the second argument, which is the 
name of a user-defined ordering function. That function should return a negative number 
if its first argument is before the second (according to the comparison function), a positive 
number if the first argument comes after the second, and zero if the elements are the 
same. 


uksort( ) 


Sorts key/value pairs by key, using a comparison function. Similar to uasort( ), except 
that the ordering is by key, rather than by value. 


usort ( ) 


Sorts an array by value using a supplied comparison function. Similar to ua so rt ( ), 
except that (as in sort( )), the key /value associations are not maintained. 



Printing Functions for Visualizing Arrays 

Before we leave this subject entirely, we should mention a couple of printing functions that are very 
useful for visualizing and debugging arrays, especially multidimensional arrays. 
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The first function is p r i n t_r ( ) , which is short for print recursive. This takes an argument of any 
type and prints it out, which includes printing all its parts recursively. For a simple value (a number 
or string), this means simply that the value is printed; for compound types like arrays and objects 
it means that all elements (and all parts of those elements) are printed. The layout that makes the 
compound structure clear involves spaces, so it's best to wrap its output in an HTML <pre></pre> 
construct so that the spaces are printed literally. 

i- C'lirjC)^^^ F_f ^ or l110re detail on the va r dump function and other ways to visualize data structures, 
see Chapter 31 on debugging. 

The var_dump( ) function is similar, except that it prints additional information about the size 
and type of the values it discovers. An example is worth a thousand words here, so we will create a 
simple multidimensional array and print it using both functions: 

<?php 

$my„array = array("keyl" => "valuel", 

"key2" => array( "subkeyl" => "value2")); 



print("The result of pri nt_r : <BRXpre> " ) ; 
pri nt_r ( $my_a r ray ) ; 
print("</pre><BR>") ; 

print("The result of va r_dump : <BRXpre> " ) ; 
va r_dump ( $my_a rray ) ; 
print("</preXBR>") ; 
?> 



The resulting output from this sample looks like this: 

The result of print_r: 

Array 

( 

[keyl] => valuel 
[key2] => Array 
( 

[subkeyl] => value2 

) 



) 



The result of var_dump: 
array(2) { 
["keyl"]=> 
string(6) "valuel" 
["key2"]=> 
array(l) { 

[ " subkeyl " ] = > 

s t r i n g ( 6 ) " v a 1 u e 2 " 

1 

} 

?> 
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Summary 

The transformation functions are designed to do interesting things to your arrays. With the excep- 
tion of s h u f f 1 e ( ) , these functions return their results as a newly created array. To treat an array as 
a stack is to give it a last-in-first-out property. You can treat an array as a stack by using the a r r ay_ 
pushO and array_pop( ) functions in tandem. Alternatively, array_unshi ft( ) and array 
s h i f t ( ) used in tandem will have a similar effect, though they work on the opposite end of the 
array. By choosing one function from each pair, you can effectively cause an array to act like a queue. 

The compa ct ( ) function maps variable names and values onto array keys and values, while 
extract( ) reverses the process, even if the array was not created with compact. Finally, a variety 
of functions in two major classes will sort and reorder arrays. The first major class will do it without 
reordering integral keys; the second will reorder your integral keys according to the new sorted order. 



369 



Examining 
Regular Expressions 



In Chapter 7 we covered PHP strings — how to create them, print them, 
and (to some extent) how to examine and modify them. In this chapter, 
we delve into more advanced string-manipulation techniques, starting 
off with functions to split up (or tokenize) strings into parts. We'll soon run 
into limitations of the basic tokenization functions, which show the need 
for regular expressions. 

Finally, we'll cover some of the more advanced string functions that enhance 
the effectiveness of regular expressions and the use of strings in general. 



Tokenizing and Parsing Functions 

Sometimes you need to take strings apart at the seams, and you have your 
own notions of what should count as a seam. The process of breaking up a 
long string into words is called tokenizing, and among other things it is part of 
the internals of interpreting or compiling any computer program, including 
PHP. PHP offers a special function for this purpose, called s t rt o k ( ) . 

The s t r t o k ( ) function takes two arguments: the string to be broken up 
into tokens and a string containing all the delimiters (characters that count 
as boundaries between tokens). On the first call, both arguments are used, 
and the string value returned is the first token. To retrieve subsequent 
tokens, make the same call, but omit the source string argument. It will be 
remembered as the current string, and the function will remember where it 
left off. For example: 

$token = strtok( 

"open-source HTML-embedded server-side Web 
scripting", 

" "); 



IN THIS CHAPTER 



Tokenizing and parsing 
Regular expression functions 
Example: A simple link scraper 



HTML functions 



Hashing functions 

Strings as character collections 

String similarity functions 
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whi 1 e( $token ) { 

print($token . "<BR>"); 
$token = strtok( " " ) ; 

} 

produces the browser output: 

open - source 
HTML-embedded 
server-side 
Web 

scri pti ng 

The original string would be broken at each space. At our discretion, we could change the delimiter 
set, like this: 

$token = strtok( 

"open-source HTML-embedded server-side Web scripting", 

whi 1 e( Itoken ) { 

print($token . "<BR>"); 
$token = strtok( " - " ) ; 

} 

This gives us (less sensibly): 
Open 

source HTML 
embedded server 
side Web scripting 

Finally, we can break the string at all these places at once by giving it a delimiter string like " 
containing both a space and a dash. The code: 

Itoken = strtokC 

"open-source HTML-embedded server-side Web scripting", 

whi 1 e( Itoken ) j 

print($token . "<BR>"); 
Stoken = strtokC " - " ) ; 

} 

prints this output: 

open 

source 

HTML 

embedded 
server 
side 
Web 

scri pti ng 
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Notice that in every case the delimiter characters do not show up anywhere in the retrieved tokens. 

The strtokC ) function doles out its tokens one by one. You can also use the expl ode( ) function 
to do something similar, except that it stores the tokens all at once in an array. After the tokens are 
in the array, you can do anything you like with them, including sort them. 

The expl ode ( ) function takes two arguments: a separator string and the string to be separated. It 
returns an array where each element is a substring between instances of the separator in the string 
to be separated. For example: 

$expl ode_resul t = expl ode( "AND" , "one AND a two AND a three"); 

results in the array $expl ode_resul t having three elements, each of which is a string: "one ", " a 
two ",and " a three". In this particular example, there would be no capital letters anywhere in the 
strings contained in the array, because the AND separator does not show up in the result. 

The separator string in expl ode () is significantly different from the delimiter string used in 
strtok( ). The separator is a full-fledged string, and all its characters must be found in the right 
order for an instance of the separator to be detected. The delimiter string of s t r t o k ( ) specifies a 
set of single characters, any one of which will count as a delimiter. This makes expl ode ( ) both 
more precise and more brittle — if you leave out a space or a newline character from a long string, 
the entire function will be broken. 

Because the entire separator string disappears into the ether when expl ode () is used, this function 
can be the basis for many useful effects. The examples given in most PHP documentation use short 
strings for convenience, but remember that a string can be almost any length — and expl ode ( ) is 
especially useful with longer strings that might be tedious to parse some other way. For instance, 
you can use it to count how many times a particular string appears within a text file by turning 
the file into a string and using expl ode () on it, as in this example (which uses some functions we 
haven't explained yet, but we hope make sense in context). 

<?php 

//First, turn a text file into a string called $filestring. 
$filename = "complex_layout.html"; 
$fd = f open ( $f i 1 ename , "r"); 

$filestring = fread($fd, f i 1 esi ze ( $fi 1 ename )) ; 
fclose ($fd); 

//Explode on the beginning of the <TABLE> HTML tag 

Stables = expl ode( "<TABLE" , $f i 1 estri ng ) ; // assumes uppercase 

//Count the number of pieces 

$num„tables = count ( $tabl es ) ; 

//Subtract one to get the number of <TABLE> tags, and echo 

echo ($num_tables - 1); 

?> 
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The expl ode ( ) function has an inverse function, i mpl ode ( ) , which takes two arguments: a "glue" 
string (analogous to the separator string inexplodeO) and an array of strings like that returned by 
expl ode (). It returns a string created by inserting the glue string between each string element in 
the array. 

You can use the two functions together to replace every instance of a particular string within a text file. 
Remember that the separator string will vanish into the ether when you perform anexplodeO — if 
you want it to appear in the final file, you have to replace it by hand. In this example, we're changing 
the font tags on a web page. 

<?php 

//Turn text file into string 
$filename = "someoldpage.html"; 
$fd = f open ( $f i 1 ename , "r"); 

$filestring = fread($fd, f i 1 es i ze ( $fi 1 ename )) ; 
fclose ($fd); 

$parts = expl ode( "ari al , sans-serif", $f i 1 estri ng ) ; 
$whole = i mpl ode ( " a ri al , verdana, sans-serif", $parts); 



//Overwrite the original file 
$fd = f open ( $fi 1 ename , "w"); 
fwrite($fd, $whole); 
fclose ($fd); 
?> 



Why Regular Expressions? 

The string-comparison and substring-finding functions we saw here and in Chapter 7 are fine as far 
as they go, but they are on the literal-minded side. As an example of their weakness, let's say that 
you want to test strings to see if they are a particular kind of web hostname: addresses that start 
with www . and end with . com, and have one lowercase alphabetic word in the middle. For example, 
these are strings we want: 

' www . i bm . com ' 
' www . zend . com ' 

And the following are not: 

'java.sun.com' 
' www . j ava . sun . com ' 
' www . php . net ' 
' www .IBM. com ' 

'www. Web addresses can't have spaces.com' 

With a little thought, it's obvious that there is no convenient way to simply use string and substring 
comparison to build the test that we want. We can test for the presence of www . and . com, but it is dif- 
ficult to enforce what should be happening between them. This is what regular expressions are good for. 



374 



Examining Regular Expressions 



22 



Regex in PHP 

Regular expressions (or regex, pronounced with a soft g by your authors, but with no consensus pro- 
nunciation) are patterns for string matching, with special wildcards that can match entire portions 
of the target string. There are two broad classes of regular expression that PHP works with: POSIX 
(extended) regex and Perl-compatible regex. The differences mostly have to do with syntax, although 
there are some functional differences, too. 

POSIX-style regular expressions are ultimately descended from the regex pattern-matching machin- 
ery used in Unix command-line shells; Perl-compatible regex is a more direct imitation of regular 
expressions in Perl. We've already waxed poetic about the utility of arrays. We're about to do it again 
with regex. If you're planning on doing any substantial coding in a web environment, sooner or later 
you will bump up against regex. 




Note that for PHP6, the ereg functions are no longer included. 



An example of POSIX-style regex 

Here are a few of the rules for POSIX-style regular expressions, simplified: 

■ Characters that are not special are matched literally. The letter a in a pattern, for example, 
matches the same letter in a target string. 

■ The special character A matches the beginning of a string only, and the special character $ 
matches the end of a string only. 

■ The special character . matches any character. 

■ The special character * matches zero or more instances of the previous regular expression, 
and + matches one or more instances of the previous expression. 

■ A set of characters enclosed in square brackets matches any of those characters — the pat- 
tern [ a b ] matches either a or b. You can also specify a range of characters in brackets by 
using a hyphen — the pattern [ a - c ] matches a , b , or c . 

■ Special characters that are escaped with a backslash (\) lose their special meaning and are 
matched literally. 

We can use the preceding rules to construct an expression that matches the kind of web address we 
want in the section "Why Regular Expressions?" earlier in this chapter. Our chosen expression is: 

A www\ . [a-z]+\ . com$ 

In this expression we have the ' A ' symbol, which says that the www portion must start at the begin- 
ning of the string. Then comes a dot (. ), preceded by a backslash that says we really want a dot, not 
the special . wildcard character. Then we have a bracket-enclosed range of all the lowercase alpha- 
betic letters. The following + indicates that we are willing to match any number of these lowercase 
letters in a row, as long as we have at least one of them. Then another literal . , the com, and the spe- 
cial $ that says that com is the end of it. 
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Now let's use that expression as an argument to the function e reg ( ) , which takes as arguments a 
pattern string and a string to match against. We can use an e reg ( ) call to build a test function for 
our kind of web address. 

function s i mpl e_dot_com ($url) 
{ 

return(ereg( ' A www\\ .[a-z]+\\.com$', $url ) ) ; 

} 

Confusingly, we have to put two backslashes in the pattern string, because PHP treats the first slash 
as an escape character for the second backslash. (You can get away with just one backslash, but that 
behavior is not guaranteed to continue in future versions of PHP.) The second backslash (escaped by 
the first), in turn, is a regex escape character for the following character. 

This function will return TRUE or FALSE, depending on whether it successfully matches our pattern. 
Now we can use our function to test some of the addresses listed earlier. 

$url s_to„test = 

array ( ' www . i bm . com ' , ' www .java.sun.com' , 
'www.zend.com', 'java.sun.com', 
'www.java.sun.com' , 'www.php.net' , 
' www . I BM . com ' , 

'www. Web addresses can\'t have spaces.com'); 
whiledtest = a rray_pop ( $url s_to_test ) ) 1 
if ( simpl e_dot_com( $test ) ) 

pr i nt ( " \ " $test \ " is a simple dot-com<BR>" ) ; 



The results of our tests are: 

"www. Web addresses can't have spaces.com" is NOT a simple dot-com 

"www.IBM.com" is NOT a simple dot-com 

"www.php.net" is NOT a simple dot-com 

"www.java.sun.com" is NOT a simple dot-com 

"java.sun.com" is NOT a simple dot-com 

"www.zend.com" is a simple dot-com 

"www.java.sun.com" is NOT a simple dot-com 

"www.ibm.com" is a simple dot-com 

This is the kind of discriminating behavior we are looking for. 



else 



pr i nt ( " \ " $test \ " is NOT a simple dot-com<BR>" ) ; 




On many Unix systems, typing man 7 regex will lead you to a guide to POSIX regular 
expressions. If that does not work, try man regex and follow any pointers to related pages. 



376 



Examining Regular Expressions 



22 



Regular expression functions 

The POSIX-style regular expression functions in PHP are summarized in Table 22-1. These are 
included for legacy applications where you might find them still being used. These functions are 
no longer in PHP6 and have been replaced with preg functions, discussed later in this chapter. 

pTp - ^ F If you find yourself using a regular expression function with a pattern that has no special 
characters, you are probably using an expensive tool where a cheap one would do. If you 
are trying to match a simple string to a simple string, you need only one of the more basic (and faster) 
functions that we cover earlier in this chapter and in Chapter 7. 



TABLE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^M 


POSIX Regular Expression Functions 


Function 


Behavior 


ereg( ) 


Takes two string arguments and an optional third-array argument. The first 
string is the POSIX-style regular expression pattern, and the second string is the 
target string that is being matched. The function returns TRUE if the match was 
successful and FALSE otherwise. In addition, if an array argument is supplied 
and portions of the pattern are enclosed in parentheses, the parts of the target 
string that match successive parenthesized portions will be copied into successive 
elements of the array. 


ereg_repl ace( ) 


Takes three arguments: a POSIX regular expression pattern, a string to do 
replacement with, and a string to replace into. The function scans the third 
argument for portions that match the pattern and replaces them with the second 
argument. The modified string is returned. 

If there are parenthesized portions of the pattern (as with e r e g ( ) ), the 
replacement string may contain special substrings of the form \ \ di gi t (that is, 
two backslashes followed by a single-digit number), which will themselves be 
replaced with the corresponding piece of the target string. 


e r e g i ( ) 


Identical to ereg( ), except that letters in regular expressions are matched in a 
case-independent way. 


eregi_repl ace( ) 


Identical to ereg_repl ace( ), except that letters in regular expressions are 
matched in a case-independent way. 


splitO 


Takes a pattern, a target string, and an optional limit on the number of portions 
to split the string into. Returns an array of strings created by splitting the target 
string into chunks delimited by substrings that match the regular expression. (Note 
that this is analogous to the expl ode ( ) function, except that it splits on regular 
expressions rather than literal strings.) 


s p 1 i t i ( ) 


Case-independent version of spl i t ( ) . 
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Perl-Compatible Regular Expressions 

Perl-compatible regex in PHP has a completely distinct set of functions and a slightly different set of 
rules for patterns. 

Perl-compatible regex patterns are always bookended by one particular character, which must be 
the same at beginning and end, indicating the beginning and end of the pattern. By convention, this 
is most often the / character, although you can use a different character if you so desire. The Perl- 
compatible pattern: 

/pattern/ 

matches any string that has the string (or substring) pattern in it. To make things slightly more 
complicated, these patterns are typically strings, and PHP needs its own quotes to recognize such 
strings. So if you are putting a pattern into a variable for later use, you might well do this: 

$my„pattern = '/pattern/'; 

This variable would now be suitable for passing off to a Perl-compatible regex function that expects 
a pattern as argument. 

Although we don't have time or space to cover Perl- compatible regex patterns in detail, Table 22-2 
shows a list of the most commonly used constructs. 



TABLE 22-2 



Common Perl-Compatible Pattern Constructs 


Construct 


Interpretation 


Simple literal 
character matches 


If the character involved is not special, Perl will match characters in sequence. The 
example pattern / a be / matches any string that has the substring 'abc' in it. 


Character class 
matches: [<//sf of 
characters>] 


Will match a single instance of any of the characters between the brackets. For 
example, / [xyz] / matches a single character, as long as that character is either x, 
y, or z. A sequence of characters (in ASCII order) is indicated by a hyphen, so that 
a class matching all digits is [ 0 - 9 ] . 


Predefined character 
class abbreviations 


The patterns \d will match a single digit (from the character class [0-9]), and the 
pattern \s matches any whitespace character. 


Multiplier patterns 


Any pattern followed by * means: "Match this pattern 0 or more times." 
Any pattern followed by ? means: "Match this pattern exactly once." 
Any pattern followed by + means: "Match this pattern 1 or more times." 
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Construct 


Interpretation 


Anchoring characters 


The caret character A at the beginning of a pattern means that the pattern must 
start at the beginning of the string; the $ character at the end of a pattern means 
that the pattern must end at the end of the string. The caret character at the 
beginning of a character class [ A a be ] means that the set is the complement of the 
characters listed (that is, any character that is not in the list). 


Escape character 'V 


Any character that has a special meaning to regex can be treated as a simple 
matching character by preceding it with a backslash. The special characters that 
might need this treatment are: 

.\ + * ?[] A $(){} = !<>| : 


Parentheses 


A parenthesis grouping around a portion of any pattern means: "Add the substring 
that matches this pattern to the list of substring matches." 



Take, as an example, the following pattern: 

/phone number\s+(\d\d\d\d\d\d\d)/ 

It matches any string that contains the literal phrase phone number, followed by some number of 
spaces (but at least one), followed by exactly seven digits (no spaces, no dash). In addition, because 
of the parentheses, the seven-digit number is saved and returned in an array containing substring 
matches if it is called from a function that returns such things. 

The Perl-compatible functions are summarized in Table 22-3. 

The most widely used of these functions are probably preg_match( ) and preg_match_all ( ). 
The first is best for simply answering whether a pattern matches a string, and the latter is best for 
either counting matches or collecting portions that match. 

The optional fourth argument to preg_match_al 1 ( ) requires a little more explanation. The array 
that contains the returned matches is going to be two levels deep, with one level being the iteration 
of the match (the first match, the second, and so on) and the other level being the position of the 
match in the pattern. (The entire match is always first, followed by any parenthesized subpatterns 
in order.) The question is: Which level is on top? Will the array be a list of positions, each of which 
contains a list of iterations, or the other way around? If the argument is PREG_PATTERN_ORDER, 
the first element will contain all matches of the entire pattern, the second element will contain all 
matches of the first parenthesized pattern, and so forth. If the argument is PREG_SET_ORDER, the 
first argument will be all the substrings from the first match (first the total match, then parenthe- 
sized bits in order), the second element will contain all the substrings from the second match, and 
so on. (See the following example to clarify.) 
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TABLE 22-3 



Perl-Compatible Regular Expression Functions 

Function Behavior 

preg_match ( ) Takes a regex pattern as first argument, a string to match against as second 

argument, and an optional array variable for returned matches. Returns 0 if no 
matches are found, and 1 if a match is found. If a match is successful, the array 
variable contains the entire matching substring as its first element, and subsequent 
elements contain portions matching parenthesized portions of the pattern. As of 
PHP 4.3.0, an optional flag of PREG_OFFSET_CAPTURE is also available. This 
flag causes preg match to return into the specified array a two-element array for 
each match, consisting of the match itself and the offset where the match occurs. 



preg_ 


_match_a 1 1 ( ) 


Like preg_ma t c h ( ), except that it makes all possible successive matches of 
the pattern in the string, rather than just the first. The return value is the number 
of matches successfully made. The array of matches is not optional (If you want 
a true/false answer, use preg_match ( )). 

The structure of the array returned depends on the optional fourth argument 
(either the constant PREG_PATTERN__ORDER, or PREG_SET_ORDER, defaulting 
to the former). (See further discussion following the table.) PREG_0FFSET_ 
CAPTURE is also available with this function. 


preg_ 


_spl it( ) 


Takes a pattern as first argument and a string to match as second argument. 
Returns an array containing the string divided into substrings, split along 
boundary strings matching the pattern. (Analogous to the POSIX-style function 
s pi i t ( ) .) An optional third argument (1 i mi t) controls how many elements to 

*;nl it npfnrp rpti irninp thp IiQt - -1 mpanQ no imit An nntinna f Lip in tnp fni irth 
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position can be PREG_SPLIT_NO_EMPTY causing the function to return only 
nonempty pieces, PREG_SPLIT_DELIM_CAPTURE causing any parenthesized 
expression in the delimiter pattern to be returned, or PRE G_S P L I T_0 F F S E T_ 

CAPTURE, which does the same as PREG_OFFSET_CAPTURE. 


preg_ 


_repl ace( ) 


Takes a pattern, a replacement string, and a string to modify. Returns the 
result of replacing every matching portion of the modifiable string with 
the replacement string. An optional limit argument determines how many 
replacements will occur (as in preg_spl i t( )). 


preg_repl ace_ 
cal 1 back( ) 


Like preg_repl a ce ( ), except that the second argument is the name of a 
callback function, rather than a replacement string. This function should return 
the string that is to be used as a replacement. 


preg_ 


_grep( ) 


Takes a pattern and an array and returns an array of the elements of the input 
array that matched the pattern. Surviving values of the new array have the same 
keys as in the input array. 


preg_ 


_quote ( ) 


A special-purpose function for inserting escape characters into strings that 
are intended for use as regex patterns. The only required argument is a string 
to escape; the return value is that string with every special regex character 
preceded by a backslash. 
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As an example of what regex can do for us, let's write a simple function to grab and print links 
from an arbitrary web page. The input will be a URL for the page we're interested in analyzing; 
the output will be a printed list of the links on the page, split into the target URL for the link 
and the descriptive text that appears in the link (the anchortexf). We will do this using Perl- 
compatible regex functions. 

Such a function might be the very first step in writing a web crawler for a search engine. Search 
engines download the contents of web pages to analyze and index them, but they also need to dis- 
cover links to other pages, if only to discover new content. 

The regular expression 

The heart of our little function will be the regular expression itself. What we need to do is design an 
expression that will match HTML links (and nothing else) and that is suitable for using to extract 
pieces of such links. 

HTML links generally look something like this: 

<A HREF=" http : //mysi te . com/mypage . php" >My cool page on my cool 
site</A> 

That is, an anchor tag that has an HREF attribute, and which encloses the anchortext between the 
start tag (<A>) and the end tag (< / A>). We'll construct a pattern to match this simplified view of 
an anchortext element. (This won't capture everything that the HTML spec permits as legal anchor 
links — in particular, you are allowed attributes in anchors other than H R E F s , but we will ignore 
that for our purposes.) 

Now, regular expressions are famously unreadable when considered all at once. So we will grow this 
one in several drafts as we explain what's going on. 

First, let's start with a minimal expression to catch a beginning anchor tag. Our first draft looks 
like this: 

/<A\sHREF="[ A "]+">/ 

// first draft of a pattern to match anchor links 

(Note that this is not yet intended to be working PHP code; we're drafting an expression that we'll 
plug into PHP code later.) 

In English, our first-draft definition of an anchor tag is left angle bracket, followed by A, followed 
by a space, followed by the string HREF=, followed by a double-quotation mark, followed by any 
number of characters that are not quotation marks, followed by a closing quotation mark, followed 
by a right angle bracket. Then the whole expression is enclosed in a pair of slashes, indicating to the 
regex engine the start and end of the expression. 
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The [ A " ] + construction in the middle of this expression breaks down like this: The brackets indi- 
cate a character set, and the caret ( A ) immediately after the left bracket indicates that we are negating 
the set — that the set contains every character that is not in the subsequent list. Finally, the + after 
that bracketed class means that we expect at least one nonquote character. 

As we've said, we're not trying to capture the precise syntax prescribed by the HTML specification. 
But there are a couple of ways that we can make this expression less strict. For one thing, as far as 
we know, there may be spaces between the initial < character and the A tag. Similarly, there may be 
an arbitrary number of spaces between the A and the H R E F or the closing double-quote and the right 
angle bracket. Adding these, the expression becomes: 

/<A\s+HREF="[ A "]+"\s*>/ 

// second draft, allowing more spaces 

Here, \s+ means one or more spaces. 

Now we add the anchortext itself and the closing </A> tag: 

/<A\s+HREF="[ A \"]+"\s*>[ A >]*<\/A> / 
// third draft, with text and close tag 

We are allowing the anchortext to be anything up until a closing anchor tag, so we make an any- 
thing-but-right-angle-bracket character class ([ A >]) and indicate that it can repeat zero or more 
times. Finally, we add the subpattern to match the closing anchor tag (<\ /A>). 

This is fine as far as it goes, but it will only match anchors where the tag name (A) and attribute 
(HREF) are in uppercase. Lowercase tags should be legal as well, so we add an i modifier after the 
entire expression, to specify case-independent matching. 

/<A\s+HREF="[ A \"]+"\s*>[ A >]*<\/A>/i 
// fourth draft, case-independent 

This draft is nearly final and could be used to give true/false answers to the question of whether 
a page contains the kind of links we like. But we want to go further and extract certain portions 
of any string that does match. We signify this by adding parentheses to enclose the portions we're 
interested in: 

/<A\s+HREF="( [ A \"]) + "\s*>( [ A >]*X\/A>/i 
// final draft, extracts portions 

They may be hard to see by this point, but we've added a pair of parentheses to enclose the target 
of the HREF (between the quotes) and another pair around the anchortext area (between the tags). 
These parentheses tell the calling function to save the string portion that matches the enclosed area, 
so that it can be added to the return array. 
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Using the expression in a function 

With an anchor-tag-matching expression in hand, our goal now is to write a function to scrape links 
from an HTML page. We'll need to: 

■ Take a URL as argument 

■ Open up an HTTP connection to the URL and grab its contents as a string 

■ Iterate through the string, applying our regex pattern wherever we can, saving what matches 

■ Print the extracted portions (target URL and anchortext) 

Such a function is shown in Listing 22-1. 



LISTING 22-1 



A print links function 

<?php 

function pri nt_l inks ($url) 
{ 

$f p = f open ( $url , "r" ) 

or die("Could not contact $url"); 
$page_contents = " " ; 
while ($new_text = fread($fp, 100)) ( 

$page_contents .= $new_text; 

} 

$match_resul t = 

preg_match_all ( ' /<A\s+HREF=" ( [ A \ " ]+) " \s*> ( [ A > ]* )<\/A>/i 
$page_contents , 
$match_array , 
PREG_SET_0RDER) ; 

foreach ( $match_array as Sentry) ( 
$href = Sentry [1] ; 
Sanchortext = $entry[2]; 
pri nt ( " <B>HREF</B> : Ihref; 

<B>ANCH0RTEXT</B>: $anchortext<BR>" ) ; 

} 

1 

?> 



This function is easier to write than you might expect because PHP takes care of several parts of it 
for us. We do not need to write anything special to make an HTTP connection to download a web 
page because f open ( ) will accept a URL as argument and do the right thing. All we need to do after 
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calling f open ( ) on the URL is to read characters until we are out of them, appending what we get 
onto a constructed string. 

The iteration through the HTML page's contents is taken care of by preg_match_al 1 ( ) , which 
applies the regex pattern as many times as possible, starting from the previous match each time, and 
saving the matches in $match_array. We chose to have the array arranged by P R E G_S E T_0 R D E R , 
meaning that each entry in the top-level array is the portion from a particular match in the iteration, 
rather than across matches. 

Applying the function 

The only argument the function requires is a URL. In testing the function before including it in the 
book, we pointed it at link-rich, top-level pages like http://slashdot.org, www . cnn . com, and 
www .php.net. Those results would be fun to display, but all of those sites have copyright notices, 
and publishers are understandably wary of allowing authors to put other people's copyrighted mate- 
rial into their copyrighted book without permission. So, instead, we pointed it at the top-level place- 
holder page for our own vanity site (www . tr outworks . com), like this: 

pri nt_J i n ks ( " http : / /www .troutworks.com/"); 
You get the following result (approximately): 

HREF: http://www.mysteryguide.com; ANCHORTEXT: MysteryGuide 
HREF: http://www.sciencebookguide.com; ANCHORTEXT: 

ScienceBookGuide 

HREF: / Joy eel og/ j oycel og . php ; ANCHORTEXT: Troutgirl weblog 
HREF: /Timl og/timl og . php ; ANCHORTEXT: Timboy weblog 
HREF: http://www.troutworks.com/phpbook; ANCHORTEXT: code 
download site 

HREF: http:/ /www .amazon.eom/exec/obidos/tg/detail/-/0764549553/; 
HREF: http://www.mysteryguide.com; ANCHORTEXT: MysteryGuide 
HREF: http://www.sciencebookguide.com; ANCHORTEXT: 
ScienceBookGuide 
ANCHORTEXT: PHP Bible 

HREF: http://www.troutworks.com/phpbook; ANCHORTEXT: code 
download site 

Just because we didn't feel that we could print the results of the links from those more interesting 
sites doesn't mean that you can't apply this code to them (however, see the warnings in the sidebar 
"Writing Weil-Behaved Spiders"). 

Extending the code 

As we've said, code like Listing 22-1 is the very beginning of writing a web search spider. If you 
want to make it more real, you could: 

■ Convert the relative links to absolute (http : / / ) links by remembering the URL that you 
are scraping and splicing that base URL appropriately with the relative path 
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■ Add a more graceful way to bounce back from an unreachable site rather than immedi- 
ately dying 

■ Expand the regex pattern to match HREFs that have quotation marks around the URL as 
well as HREFs that do not 

■ Add capability for recursive calls so that, rather than simply printing a child link, you 
apply the same function again to it and explore its own links 



Writing Weil-Behaved Spiders 

A note of caution, however (informed by the experience of one of your authors in the search engine busi- 
ness). There are two rules that you should observe, though, before writing any kind of spider that does 
more automated crawling. When you crawl any site, you should: 

■ Check to see if there is a robots . txt file (at http : //si tename/ robots . txt). If there is no 
such file, the site owners are implicitly saying the site is okay to crawl. If there is such a file, you 
should either not crawl the site or, if you do, you should make sure that you are not crawling pages 
that match the patterns laid out in that file. (For more on this, do a web search for "robot exclusion 
standard".) 

■ Make sure that you don't request files from any particular site too frequently. A decent interval to wait 
between requests is 1 0 seconds or so. (You can implement this delay on a per-site basis, or simply by 
sleeping for 1 0 seconds between every request.) It is not OK to simply create a recursive version of 
the preceding code and then unleash it on a large site, grabbing new links and pages as fast as your 
code can loop. Remember: One man's search engine is another's denial-of-service attack. 



Advanced String Functions 

We have now covered the most basic things to do with strings, as well some more sophisticated 
means of working with them via regular expressions. Now, we'll delve into some more exotic string 
functions, which we've categorized by type and/or purpose. These are the sort of functions that 
might only be relevant to you if you're working on a particular kind of project. Some of these sec- 
tions might make you want to say, "Why would anyone want to do that?" If so, please ignore them 
until you the day that you suddenly realize that you need to do that thing exactly. 

HTML functions 

PHP offers a number of web-specific functions for string manipulation, which are summarized in 
Table 22-4. 
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TABLE J^/j^^^////////////////////^^ 


HTML-Specific String Functions 


Function 


Behavior 


html speci al chars ( ) 


Takes a string as argument and returns the string with replacements for four 
characters that have special meaning in HTML. Each of these characters is 
replaced with the corresponding HTML entity, so that it will look like the 
original when rendered by a browser. The & character is replaced by & " " 
(the double-quote character) is replaced by &quot ;; < is replaced by & 1 1 ; ; > 
is replaced by &gt ;. 


html enti ti es ( ) 


Goes further than htmlspecialcharsO, in that it replaces all characters that 
have a corresponding HTML entity with that HTML entity. 


get_html_ 
transl ati on_ 
tableO 


Takes one of two special constants (HTML„SPECIAL_CHARS and HTML_ 
ENTITIES), and returns the translation table used byhtmlspecialcharsO 
and html enti ti es ( ), respectively. The translation table is an array where keys 
are the character strings and the corresponding values are their replacements. 


nl2br() 


Takes a string as argument and returns that string with <br / > inserted before all 
newlines(\n, \r or \ r\r). This is helpful, for example, in maintaining the 
apparent line length of text paragraphs when they are displayed in a browser. 


s t r i p_t a g s ( ) 


Takes a string as argument and does its best to return that string stripped of all 
HTML tags and all PHP tags. 



Hashing using MD5 

MD5 is a string-processing algorithm that is used to produce a digest or signature of whatever string 
it is given. The algorithm boils its input string down into a fixed-length string of 32 hexadecimal 
values (0,1,2, . . . 9,a,b, . . . f). MD5 has some very useful properties: 

■ MD5 always produces the same output string for any given input string, so it is not appro- 
priate to use MD5 to store passwords. 

■ The fixed-length results of applying MD5 are very evenly spread over the range of 
possible values. 

■ It may be possible produce an input string corresponding to a given MD5 output string or 
to produce two inputs that yield the same output. 

PHP's implementation of MD5 is available in the function md5 ( ) , which takes a string as input and 
produces the 32-character digest as output. For example, evaluating this: 

print("md5 of 'Tim' is " . md5('Tim') . "<BR>"); 
print("md5 of 'tim' is " . md5('tim') . "<BR>"); 
print("md5 of 'time' is " . md5( ' time ' ) . "<BR>"); 
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gives us the browser output: 

md5 of Tim is dc2054afd537ddc98afd9347136494ac 
md5 of tim is Dl5d47e99831ee63e3f47cf 3d4478e9a 
md5 of time is 07cc694b9b3f c636710f a08b6922c42b 

Although the input strings seem close to each other in some sense, there is no apparent similarity in 
the output strings. And since the range of possible output values is so huge (16 to the 32nd power), the 
chances that any two distinct strings will collide by producing the same MD5 value is vanishingly small. 

The characteristics of MD5 make it useful for a wide variety of tasks, including: 

■ Checksumming a message or file: If you are worried about errors that might happen in 
transfer, you can transmit an MD5 digest, along with the message, and run the message 
through MD5 again after transfer. If the two versions of the digest do not match, then 
something is amiss. 

■ Detecting if a file's contents have changed: Similar to checksumming, MD5 is often used 
in this way by search engines as a check on whether a web page has changed, making re- 
indexing necessary. It is cheaper to store the MD5 digest than the entire original file. 

■ Splitting strings or files into buckets: If you want to divide a set of strings into N ran- 
domly dispersed sets, you can MD5 the strings, take the first few hex characters, translate 
them into a number, and take that number modulo the number of bins you want. 

In addition to the md5 ( ) function, PHP offers md5__f i let), which takes a filename as argument and 
returns an MD5 hash of the file's contents. 

Strings as character collections 

PHP offers some pretty specialized functions that treat strings more as collections of characters than 
as sequences. 

The first is s t r s p n ( ) , which you can use to see what portion of a string is composed only of a given 
set of characters. For example: 

$twister = "Peter Piper picked a peck of pickled peppers"; 

$charset = "Peter picked a"; 

print("The segment matching '$charset' is " . 

strspn($ twister, $charset) . " characters long"); 

gives us: 

The segment matching 'Peter picked a' is 26 characters long 

because the first character not found in $charset is the o in of , and there are 26 characters that 
precede it. 
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The strcspn ( ) function (where that internal c stands for complement) does the same thing, except 
that it accepts characters that are not in the character set argument. For example, the statement: 

echo(strcspn($twister, "abed")); 

prints the number 14, because it accepts a 14-character sequence with the last character being the c 
in pi eked. 

Finally, hark back to Chapter 8 on arrays and check out the following for an acute analysis of 
alliteration: 

$twister = "Peter Piper picked a peck of pickled peppers"; 
print ( "$twister<BR>" ) ; 

$1 etter_array = count_chars ( $twi ster , 1); 
while ( $ eel 1 = each ( $1 etter_array ) ) { 

$letter = chr( $cel 1 [ ' key ' ] ) ; 

$frequency = $cel 1 [ ' val ue ' ] ; 

pri nt( "Character : '$letter'; frequency: $f requency <BR> " ) ; 

} 



This gives the browser output: 



Peter Piper 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 



picked a peck 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 
frequency 



of pickled peppers 
7 
2 
1 
3 
2 
8 
1 
3 
3 
1 
1 
7 
3 
1 
1 



The count_cha rs ( ) function returns a report on the occurrences of characters in its string argu- 
ment, packaged as an array where the keys are the ASCII values of characters, and the values are 
the frequencies of those characters in the string. The second argument to count_cha rs ( ) is an 
integer that determines which of several modes the results should be returned in. In mode 0, an 
array of key/value pairs is returned, where the keys are every ASCII value from 0 to 255, and the 
corresponding values are the frequencies of each character in the string. Modes 1 and 2 are variants 
that include only ASCII values that occurred in the string (mode 1) or that did not occur (mode 2). 
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Finally, modes 3 and 4 return a string instead of an array, where the string contains all characters 
that occur (mode 3) or do not occur (mode 4). 

These functions are summarized in Table 22-5. 



r ( y r ~ J- y r V For an explanation of how to take apart array formats like that returned by count 
^^•""■™""™*~ c h a r s ( ) , see Chapter 8. The c h r ( ) function used in the preceding example, which 
maps from ASCII numbers to the corresponding characters, is covered in Chapter 5. 



TABLE 22-5 



Functions for Examining Character Contents 


Function 


Behavior 


count_cha rs ( ) 


Takes a single string argument and an integer mode argument from 0 to 4. Returns 
a report about frequencies of characters in the string argument, as either an array 
or a string. (See the preceding text for more detail.) 


strspn ( ) 


Takes two string arguments and returns the length of the initial substring of the first 
argument that is composed entirely of characters found in its second argument. 


strcspn ( ) 


Takes two string arguments and returns the length of the initial substring of the first 
argument that is composed entirely of characters that are not found in its second 
argument. 



String similarity functions 

How similar is this string to that string? Well, it depends what you mean by similar, right? 

If the kind of similarity you want is similarity of spelling, consider the Levenshtein metric. The 
levenshtein( ) function takes two strings and returns the minimum number of additions, dele- 
tions, and replacements of letters needed to transform one into the other. For example: 

■ 1 evens htei n (' Ti m ' , ' Time ') returns 1. 

■ 1 evenshtei n ( ' boy ' , ' chef boya rdee ') returns 9. 

■ 1 evenshtei n (' never ' , ' cl ever ') returns 2. 

If the similarity you are interested in is phonetic , consider the functions s o u n d e x ( ) and m e t a - 
phone ( ) . Both of them take an input string and return a key string representing the pronunciation 
category of the word (in English). If two input word strings map to exactly the same output key, they 
most likely have a similar pronunciation. 
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Summary 



PHP has a wealth of built-in functions for handling strings — functions to create them, stick them 
together, chop them up, and do various kinds of analysis. The simplest of these were covered in 
Chapter 7, and in this chapter we saw functions for tokenizing, hashing, character counting, and 
determining similarity, as well as HTML-specific functions. 

Simple string matching is all very well, but when you need industrial-strength pattern matching, 
nothing less than regex will do. PHP6 removes the ereg functions, preferring instead the preg func- 
tions for pattern matching. 
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This chapter contains information on the multiplicity of system 
functions built into PHP. Many of these functions duplicate system 
functions via HTTP. Among the most useful are file-reading and 
-writing functions and those that return dates or times. 



Many of the functions in this chapter have serious security 
implications. You are inviting bad news if you use them without 
thinking pretty hard about the consequences! We'll try to point out the scari- 
est ones as we go, but nothing that allows the system to be altered via HTTP 
should be undertaken lightly. 

Some of these functions are Unix-only. The Windows system is deliberately 
made less available to users, especially to non-administrator users, and lacks 
many utilities that Unix-heads take for granted. If you're having problems and 
you run on Windows, make sure the function is enabled on your platform. 



IN THIS CHAPTER 



Understanding PHP file 
permissions 

File reading and writing 
functions 

Filesystem and directory 
functions 

Network functions 

Date and time functions 

Calendar conversion functions 



Understanding PHP File 
Permissions 

Many PHP users, who have a developer orientation rather than any sysad- 
min experience, unfortunately do not take the time to understand Unix 
filesystem permissions. You really need to have a firm grasp of the basics to 
make good decisions about using many of the functions in this section. If 
you already do, feel free to skip the rest of this section. 



391 



Part III 



More PHP 



Unfortunately, most explanations of the subject are quite general and user's eyes can easily glaze 
over in a hail of rwxes and three-digit numbers. So we're going to break it down for you into two 
simple default rules specifically for PHP users. 

■ Unless you have a good reason to do otherwise, the PHP files that you wish to make public 
should all be set to 644 (rw-i — r- -). 

■ Unless you have a good reason to do otherwise, the PHP-enabled directories that you wish 
to make public should all be set to 7 51 (rwx r - x - - x). 

For some reason, many users seem to believe that PHP files need to be executable. This is only true 
for files that you write with the intention of their being called on the command line (for example, . / 
my s c r i p t . p h p). Files that will be run through a web server only need to be readable by the web 
server user (usually Nobody, or some other user with very limited permissions). It's rather inconve- 
nient to make the files not writable by you (and doesn't really matter if you own the parent direc- 
tory), which is why our default recommendation is 644 (rw- 1 — l — ) rather than 444 (i — r--i — ), 
but this is a matter of convenience only. 

Directory permissions are also very often misunderstood. Many users seem to believe that directo- 
ries need to be readable for files to run. Actually the read directory permission means a user can list 
the contents of that directory (via the 1 s command, for instance). The execute directory permission 
is closer to what we think of as readable. For your PHP scripts to run, the directory needs only to 
be world-executable (7 51 or rwxr-x - -x). Do not make the directory writable by others unless you 
know what you're doing. 



File Reading and Writing Functions 

This is a supremely useful set of functions, particularly for data sets too small or scattered to merit 
the use of a database. File reading is pretty safe unless you keep unencrypted passwords lying 
around, but file writing can be quite unsafe. 

pTn™ [ Remember that although the web server (and client-side languages such as JavaScript) 

can only act on files located under the document root, unless the open_basedi r value 
or another chroot mechanism is set, PHP can access files at any location in the file system — including 
those above or entirely outside the web server document root — as long as the file permissions and 
i ncl ude path are set correctly. For instance, if your web server document root is located at /usr/ 
1 ocal /apache/htdocs, Apache will be able to serve only files from this directory and its subdirecto- 
ries, but PHP can open, read, and write to files in / usr/local, /home/php, / export/home /httpd 
or any other directory that you make readable and includable by the PHP and/or web server user. 

A file manipulation session might involve the following steps: 

1. Open the file for read/write. 

2. Read in the file. 

3. Close the file (may happen later). 
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4. Perform operations on the file contents. 

5. Write the results out. 

Each step has a corresponding PHP filesystem function. 

This archetypal example illustrates some subtleties of the syntax for manipulating file contents: 

$fd = f open ( $f i 1 ename , "r+") 

or die("Can't open file $f i 1 ename ") ; 
$fstring = fread($fd, f i 1 esi ze( $fi 1 ename) ) ; 
$fout = fwrite($fd, Ifstring); 
fclose($fd); 

The effect of this particular example will be to double the file — in other words, the end result will 
be a file with the original contents of the file written out twice. This function will not overwrite the 
file, as you might expect. In the following sections, we walk you through this archetypal file manip- 
ulation session, step by step. 

File open 

It's essentially mandatory to assign the result of f open () to a variable (traditionally $f d for file 
descriptor, or $fp for file pointer). 

'"'~ s ^°' e tna * f °P en ( ) does not return an integer on success. In fact, it returns a resource 
UoDnBMf t na t says Resource i d #n, where n is the number of the currently opened stream. Do not 
attempt to test the success of your file open by using i s_i nt ( ) or i s_numeri c ( ). Use di e ( ) instead. 

If it's successful in opening the file, PHP will return a resource ID, which it requires for further oper- 
ations such as f read or fwri te. Otherwise, the value will be f al se. 

"-- 0"[\J : The system makes only a certain number of file descriptors available, which is a good 
J - - ' argument for closing files as soon as you can. If you anticipate a large demand and have 

access to system settings, you may increase the number. However, if you fail to close a file descriptor, 

PHP will do it for you when the script ends. 

Files may be opened in any of six modes (similar to permissions levels). If you try to do mode- 
inappropriate things, you will be denied. The modes are: 

■ Read-only ("r"). 

■ Read and write if the file exists already (" r+"): will write to the beginning of the file, 
doubling the original contents of the file if you read the file in as a string, edit it, and then 
write the string out to the file. 

■ Write-only (" w " ) will create a file of this name, if one doesn't already exist, and will erase 
the contents of any file of this name before writing! You cannot use this mode to read a file, 
only to write one. 
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■ Write and read even if the file doesn't exist already ("w+") will create a file of this name, if 
one doesn't already exist, and will erase the contents of any file of this name before writing! 

■ Write-only to the end of a file whether it exists or not (" a "). 

■ Read and write to the end of a file whether it exists or not (" a+ " ), "doubling" original contents 
of the file if you read the file in as a string, edit it, and then write the string out to the file. 

You need to be very sure you have read in the contents of any preexisting file before using w or w+ 
on it. Your chances of losing data with the other modes is much less. 

There are several types of file connections that can be opened, including HTTP(S), FTP(S), standard 
I/O, filesystem, and others as shown at http : / / p h p . net/manual /en/wrappers . php. 



An HTTP f open ( ) tries to open an HTTP 1.0 connection to a file of a type 0 that would normally 
be served by a web server (such as HTML, PHP, ASP, and so on). PHP actually fakes out the web 
server so that it thinks the request is coming from a normal web browser surfing the 'Net rather 
than a file-open operation. 

You should be able to use forward slashes like this on either Unix or Windows, since the addresses 
are URLs rather than filepaths: 

$fd = f open (" http :/ /www . exampl e . com/openfi 1 e . html /" , "r"); 

Remember that technically a URL without a trailing slash is malformed, but through incorrect usage 
most web servers will automatically rewrite the URL with the slash and try redirecting it. Versions 
of PHP before 4.0.5 did not support redirects, so all HTTP f open ( ) requests would fail without the 
trailing slash. After 4.0.5, the trailing slash became optional. 

Remember that you need not necessarily use an HTTP connection just because you're looking at an 
HTML file. If you have filesystem access, you can open from the filesystem instead and treat the file 
as a text file. The HTTP f open ( ) alternative is mostly useful for getting HTML pages from remote 
web servers — as when you try to "scrape" data from an HTML page. The effect will be much like 
viewing an HTML page and saving the source code. 

PHP versions older than 4.3.0 were unable to make HTTPS f opens. Now, you can accomplish this 
simply by using "https://" rather than "http://". 

HTTP f open ( ) s are read-only. You will not be able to write to a remote HTML file using this type 
of file manipulation. 




rTn™ f Some users have reported problems with the "+" modes. Many of these problems actually 
appear to be caused by slightly faulty understanding of the six modes. When in doubt, try 
opening in separate read and write modes. See the section on file writing later in this chapter. 



HTTP fopen 



394 



Working with the Filesystem 



FTP fopen 

An FTP f open ( ) attempts to establish an FTP connection to a remote server by pretending to be an 
FTP client. This is the trickiest of the four options because you need to use an FTP username and 
password in addition to the hostname and path. 

$fd = fopen("ftp://username: password@exampl e.com/openfile.txt/", 
" r " ) ; 

The FTP server must support passive mode for this method to work correctly. Also, FTP file opens 
can only be read or write, not both at once, and writes can only be to new files, not to existing ones. 

PHP has many specific FTP functions, sufficient to implement a complete FTP client in PHP. If you 
want to do anything except a simple FTP file download, you should probably use them instead. See 
the PHP manual at www .php.net/manual/en/ref.ftp.php. 

Standard I/O fopen 

Standard I/O read/writes are indicated byphp://stdin,php://stdout,orphp://stderr 
(depending on the desired stream). The standard I/O f open ( ) comes into play mostly when PHP is 
used on the command line or as a system scripting language, a la Perl, because standard I/O is usu- 
ally associated with terminal windows. 

A command-line script using a standard I/O fopen looks like this: 

#! /usr/local/bin/php 
<?php 

$fp = f open ( " php : / /stdi n " , "r"); 
while ( !feof($fp) ) ( 
echo fgets($fp, 4096) ; 

1 

echo " \ n " ; 
?> 

You would run it like this from a Linux/Unix command line (Windows would require the PHP 
interpreter to be called from the command prompt itself). 

echo "goo goo ga ga" | . /stdi n_test . php 
Filesystem fopen 

The most common and useful way to use f open ( ) is from the filesystem. Unless specifically 
directed otherwise, PHP will attempt to open from the filesystem. 

On Windows systems, you can choose to use the Windows format with backslashes if desired — but 
remember to escape them: 

$fp = fopen (" c : \ \php\ \phpdocs\\navba r . i nc" , "r"); 
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You can use forward slashes from both Windows and Unix. You should not use a trailing slash for 
filesystem fopen( ) calls. 

ri*n v " [ Remember that your files, and potentially your directories, need to be readable or writ- 
• able by the PHP (or web server, if module) process UID rather than by you as a system 
user. If you share a server, this means any of the other legitimate PHP users may be able to read and/or 
write to your files. 



File read 

The f read ( ) function takes a file-pointer identifier and a file size in bytes as its arguments. If the 
file size given is not sufficient to read in the whole file, you will have mysterious problems (unless 
you're passing in a smaller file size on purpose, which is useful when reading huge files in chunks). 
Unless you have a reason to do otherwise (such as a huge, unwieldy file), it's best just to let PHP fill 
in the file size itself, by using the f i 1 es i ze ( ) function with the name of the file (or a variable) as 
the argument: 

$fstring = fread($fd, f i 1 esi ze ( $f i 1 ename ) ) ; 

A common error is to type f i 1 es i ze ( $f d ) rather than f i 1 es i ze ( $f i 1 ename ) . You may not 
remember this from the initial example, because in the intervening paragraphs, we've called the 
used f open ( ) with an actual filename rather than a variable to which that name has been assigned, 
as in the first example. 

This is an extremely useful function because it allows you to turn any file into a string, which can 
then be manipulated with PHP's large variety of useful string functions. Any string can also be bro- 
ken up into an array through use of a function like file() orexplodeO, which gives you access 
to the large arsenal of PHP array-manipulation functions. PHP gives you more slicing and dicing 
functions than a whole set of Ginsu knives! 

If you wish to send the entire contents of a file to standard output (meaning, for most PHP installa- 
tions, echoing it to the web browser window), use readf i 1 e ( ) instead. This function has file open- 
ing built in, so you need not use a separate function to open the file first. The readf i 1 e ( ) function 
is equivalent to the combination of f o p e n ( ) and fpassthru( ). 

Beginning with PHP 4.3.0, a new function called f i 1 e„get„contents ( ) was made available. This 
function returns the entire contents of a file as a string, including the f open ( ) . It is equivalent to 
fopen() andfread(),orto readf i 1 e ( ) except returning the contents as a string rather than 
straight to standard output. 

If you wish to read in and perform operations on a file line by line, you can use f gets ( ) instead 
of f read ( ) . Beginning in PHP 4.2.0, if you do not specify a line length as the second argument to 
f gets ( ) , the function will default to 1024 bytes per line. 

$fd = f open ( " sampl ef i 1 e . i nc" , "r") or die('Cannot find file'); 
while (!feof($fd)) ( 

$line = fgets($fd, 4096) ; 
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if ($line === $ta rgetl i ne ) 
{echo "A match was found!";) 

} 

fclose($fd) ; 

If you would rather read the file in as an array, you can use the function f i 1 e ( ) instead. You might 
want to do this if you're reading one of the many types of data files that use newlines to indicate 
rows — such as a spreadsheet saved to tab-delimited text format. This creates an array, each element 
of which is a line from the original file, including an ending newline character. The function f 1 1 e ( ) 
does not require a separate file open or file close step. A single operation using f i 1 e ( ) , such as: 

$line_array = f i 1 e( $f i 1 ename ) ; 
is the equivalent of this: 

$fd = f open ( $fi 1 ename , "r") or die("Can't open file $f i 1 ename" ) ; 
Sfstring = fread($fd, f i 1 esi ze( $fi 1 ename) ) ; 
$line_array = expl ode ( " \n " , $fstring); 

"""-v ; ' The filet ) function will work correctly only when PHP recognizes newlines. Hopefully, 
PHP will handle newlines from other operating systems correctly — current Windows 
and Unix versions of PHP seem to identify newline characters from the other operating system — but 
we cannot guarantee that this will be true of every case. 

Finally, if you'd like to read in a file character by character, you can use the f getc ( ) function. This 
will return a character from the file pointer, until the end-of-file. In practice, this function is not 
used very much, because it's so inefficient to read in a file one character at a time. You'd probably 
use f getc t ) only in situations where you wanted to test the first or second character in the file. 

Constructing file downloads by using fpassthru() 

Besides reading in a file for manipulation by PHP, you can use fpassthrut ) in combination with 
the PHP header ( ) construct to assemble and send file downloads. For instance, let's say you keep 
lots of tab-delimited data lying around in files, and occasionally you need to let someone download 
some data from them. Your users are typical businesspeople, not techies, so you know they use IE 
and would prefer the data as an Excel spreadsheet. So you give the user an HTML form that he or 
she can use to ask for the data from a particular day, and when it submits you assemble a download 
and send it like so: 

<?php 

// This example assumes there is one data file per day, 

// and your form lets the user specify the date they want to 

// see. 

$f1 1 e = $_P0ST['date']. ' .txt' ; 

$fp = $fopen($file, "r") ; 

headert" Content- Type:appli cat ion/xls"); 
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header("Content-Disposition:attachment; 

filename=$_POST[ 'date' ] .xl s") ; 

// Notice we changed the file name and type 

header("Content-Transfer-Encoding:binary"); 

f passthru ( $f p) ; 

?> 



~ "j" ^"''jxj'" ' F " e c ' own ' oac ' s PHP are sufpfisifg'y tricky because every browser implements the file 

download behavior differently — even different versions of the same browser can have 
different behaviors. The preceding method works fine in IE 6.0, but in Mozilla 1.0 the file will claim to 
be of type application.xls but will download as 20020526. xls.php. Most of the methods neces- 
sary to get a perfect file download are hacks and involve tricking the browser into thinking it's down- 
loading the file directly — for instance by tacking /$ P0ST[ ' data ' ] . xl s onto the end of the URL 
(for example, http://example. com /sample. php/20020526.xls). Also, if you saved the script 
above as data . xl s, and jiggered your web server into parsing . xl s files as PHP, you could get a great 
download in just about every browser. No single perfect method exists for every browser, but this is 
one situation where you can't just go by what you read in the PHP online manual. 



File write 

j Cj'J^^ [ ^ or wr 't' n g v ' a PHP, directory permissions must be set to at least 703. 



File writing is pretty straightforward if you've successfully opened in the correct mode 
for your intended purpose. The function f w r i t e ( ) takes arguments of a file pointer and a string, 
with an optional length in bytes, which should not be used unless you have a specific reason to do 
so. It returns the number of characters written. 



$fout = fwrite($fp, $fstring); 
if ($fout != strl en( $f stri ng) ) ( 
echo "file write failed!"; 

} 



The function f puts ( ) is identical to fwri te ( ) in every way. They are simply aliases for one 
another, but f puts ( ) is the C-style function name. 

Keep in mind that opening a file in w or w+ modes will result in the complete and utter obliteration 
of any file contents. These modes are meant for clean overwrites only. If you want to write to the 
beginning or end of a file, use r+ or a+, respectively. 

Probably the most common error with PHP file writing modes involves using a web interface (in 
other words, an HTML form) to edit a text file. If you want to open a file, read in and view the con- 
tents, then write an edited version to the same filename, you cannot depend on w+ mode. The w 
modes erase the contents of the file immediately upon opening it — thus, although you can f read ( ) 
from a w+ file, there will be no text to read until after you write to it. To get around this issue, you 
need to open once in read mode and once in write mode, as in the following example: 

< ? p h p 

if (IsSet($_P0ST['submitted'])) { 
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$fd = f open ( $f i 1 ename , "w+") 

or die("Can't open file $f i 1 ename" ) ; 
$fout = fwrite($fd, $_P0ST[ ' newstri ng ' ] ) ; 
fclose($fd) ; 

} 

$fd = f open ( $fi 1 ename , "r") or die("Can't open file Sfilename"); 
$initstring = freaddfd, f i 1 esi ze ( $fi 1 ename )) ; 
fclose($fd) ; 
echo "<HTML>" ; 

echo "<F0RM METH0D= ' POST ' ACTION=\"$_SERVER[ ' PHP_SELF ' ]\">" ; 
echo "<INPUT TYPE='text' SIZE=50 NAME= ' newstri ng ' 
VALUE=\"$initstring\">" ; 

echo " < I N PUT TYPE= ' HIDDEN ' NAME= ' submi tted ' VALUE=1>"; 
echo "<INPUT TY PE= ' SUBMIT '> " ; 
echo "</F0RM>"; 
echo "</HTML>" ; 

?> 

Let us reiterate that file writing is not at all a good idea unless you can control your environment 
very tightly! In other words, a well-hardened intranet server might be appropriate, but file writing 
on a production web site can be a security risk. For more information, see Chapter 28. 

As we explain in Chapter 29, in PHP there is now a very easy mechanism to disable the capability 
to file write. This is a great idea especially if your site is entirely database-driven, in which case you 
don't have any legitimate need to write to the filesystem with PHP anyway. To disable file writing, 
simply add f w r i t e to the list of disabled functions in p h p . i n i : 

di sabl ed_f uncti ons = "fwrite" 

If you don't use p h p . i n i and need to set this value in Apache httpd.conf, remember that it 
requires a php_admi n_val ue flag (rather than php_val ue): 

php_admi n_val ue di sabl ed_f uncti ons = " fwr i te" ; 

File close 

File closing is straightforward: 
fclose($fd) ; 

Unlike f open ( ) , the result of f cl ose ( ) does not need to be assigned to a variable. File closing may 
seem like a waste of time, but your system has only so many file descriptors available, and you may 
run out if you do not close your files. On the other hand, PHP will close all open files when your 
script ends, and at least one version of PHP3 had a buggy f cl ose ( ) function, which would crash 
the server. You know your own setup best, and you can make the call. 
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Filesystem and Directory Functions 

Most of these functions will be quite familiar to Unix users, as they closely replicate common system 
commands. 

r- i ' '' '■'[ ' Many of the functions in this section are dangerous. Because they duplicate func- 

s -'- r - w tions that can and should be performed from the local system, they can be a cracker's 

bonanza without providing much value to legitimate users. Strongly consider disabling them using 
PHP's di sabl e_f uncti ons directive (as discussed in the preceding section on file writing)! 

The one piece of good news is that some of these functions will only work if the PHP process is run- 
ning as the superuser. Because this is not the default case in the web browser, presumably these 
functions are intended to be used by the scripting version of PHP, and only trusted users who know 
what they're doing are even in a position to shoot themselves in the foot this way. Of course, if you 
are foolish enough to run your web server as root, you are doubly screwed. 

The most common and safest functions are listed first in the following sections; the less common 
and less safe are listed in Table 23-1. 

feof 

The feof function tests for end-of-file on a file pointer and takes a filename as argument. It's used 
mostly in a whi 1 e loop to perform the same function on each line in a file: 

while (!feof($fd)) { 

$line = fgets($fd, 4096) ; 
echo $1 i ne ; 

} 

file_exists 

The f i 1 e_exi sts function is a simple function you will use again and again if you use filesystem 
functions at all. It simply checks the local filesystem for a file of the specified name. 

if ( ! f i 1 e_exi sts ( "testf i 1 e . php" ) ) { 
$fd = f open ( "testf i 1 e . php" , "w+"); 

} 

The function returns true if the file exists, f a 1 s e if not found. The results of this test are stored in 
a cache, which may be cleared by use of the function clearstatcache(). 

filesize 

Another simple but useful function is filesize, which returns and caches the size of a file in bytes. 
We use it in all the f read ( ) examples earlier in this chapter. Never pass in a filesize as an integer if 
you can do it by using f i 1 es i ze ( ) instead. 
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Filesystem Functions 


Function 


Description 


basename (filepath, 
[suf f i x] ) 


Returns the filename portion of a stated path. 


chgrp(file, group) 


Changes file to any group to which the PHP process belongs. Inoperative 
on Windows systems. 


chmod(file, mode) 


Changes to the stated octal mode. Inoperative on Windows systems. 


chown(file, user) 


If executed by the superuser, changes file owner to stated owner. 
Inoperative but returns true on Windows systems. 


cl ea rstatcache 


Clears cache of file status info. 


copy (file, 
destination) 


Copies file to stated destination. 


delete(file) 


See "u n 1 ink." 


di rnaine(path) 


Returns the directory portion of a stated path. 


disk free spaceC 
Vdir") 


Returns the number of free bytes in a given directory. 


fnptrsvffn Ipnoth 
delimiter [ , 
end osure] ) 


Reads in a line and parses it for CSV format. 


fgetss(fp, length [, 
a 1 1 owabl e_tags ] ) 


Gets a tile line (delimited by a newhne character) and strips all HTML and 
PHP tags except those specifically allowed. 


fileatime(file) 


Returns (and caches) last time of access. 


f i 1 ectime (f i 1 e) 


i-» ■ / 1 1 \ 1 ■ ■ • c • 1 1 

Returns (and caches) last time of mode change. 


filegroup(file) 


Returns (and caches) file group ID number. Names can be determined by 
using posi x_getgrgi d ( ). 


f i 1 ei node ( file) 


Returns (and caches) file inode. 


f i 1 emti me (file) 


Returns (and caches) last time of modification. 


f i 1 eowner ( file) 


Returns (and caches) owner ID number. Names can be determined by 
using posi x_getpwui d ( ). 


f i 1 eperms (file) 


Returns (and caches) file permissions level. 



continued 
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Filesystem Functions 


Function 


Description 


f i 1 etype (file) 


Returns (and caches) one of: f i fo, char, di r, bl ock, link, f i 1 e, 
u n known. 


flockCfile, 
operati on 
[,&wouldblock]) 


Advisory file locking. Operation value must be L0CK_SH (shared), 
L0CK_EX (exclusive), L0CK_UN (release), or L0CK_NB (don't block while 
locking). The optional third parameter is set to true if enforcing the lock 
would block existing access. 


fpassthru(fp) 


Standard output of all data from file pointer to EOF. 


fseek(fp, offset, 
whence ) 


Moves file pointer offset number of bytes into file stream from the position 
indicated by whence. 


f te 1 1 ( f p ) 


Returns offset position into file stream. 


stream_set_wri te_ 
buffer(fp [, 
buffersi ze] ) 


Sets a buffer for file writing; the default is 8K. 


I s_di r ( di rectory ) 


Returns (and caches) true if named directory exists. 


I s_executabl e ( f i 1 e ) 


Returns (and caches) true if named file is executable. 


Is_file(file) 


Returns (and caches) true if named file is a regular file. 


Isjink(file) 


Returns (and caches) true if named file is a symlink. 


I s_readabl e ( f i 1 e ) 


Returns (and caches) true if named file is readable by PHP. 


is_wri table (file/ 
di rectory ) 


Returns (and caches) true if named file or directory is writable by PHP. 


link(target, link) 


Creates hard link. Inoperative on Windows systems. 


1 i nki nf o ( path ) 


Confirms existence of link. Inoperative on Windows systems. 


mkdir(path, mode) 


Makes directory at location path with the given permissions in octal mode. 


pel ose ( f p ) 


Closes process file pointer opened by popen ( ) . 


popen ( command , mode) 


Opens process file pointer. 


readlink(link) 


Returns target of a symlink. Inoperative on Windows systems. 


rename( ol dname , 
newname ) 


Renames file. 



402 



Working with the Filesystem 



Function 


Description 


rewi nd ( f p ) 


Resets file pointer to beginning of file stream. 


rmdi r ( di rectory ) 


Removes an empty directory. 


s t a t ( f i 1 e ) 


Returns a selection of info about file. 


1 stat ( f i 1 e ) 


Returns a selection of into about tile or symlmk. 


syml i n k( ta rget , 
1 ink) 


Creates a symlink from target to link. Inoperative on Windows systems. 


touch ( fi 1 e , [time]) 


Sets modification time; creates file if it does not exist. 


umask(mask) 


Returns umask, and sets to mask & 0777. With no argument passed, it 
simply returns the umask. 


unHnk(file) 


Deletes file. 


Network Functions 



The network functions are a bunch of relatively little used functions that provide network informa- 
tion or connections. Many of these may be more useful from the command line than the web page, 
unless you're writing some kind of monitoring tool. 



Syslog functions 

The syslog functions allow you to open the system log for a program, generate a message, and close 
it again. 

■ openl og( [ident] , option, faci 1 i ty ) is entirely optional when used with sysl og () . 
The ident value is generated automatically. 

■ sysl og ( pri or i ty , message ) generates a system log entry. 

■ cl osel og ( ) is entirely optional when used with sysl og ( ) . It takes no arguments. 

DNS functions 

PHP offers some very slick DNS-querying functions, outlined in the Table 23-2. These functions 
allow PHP scripts to do some jiggering between IP address (which is available via the Apache 
REM0TE_ADDR variable, for instance) and hostname, or vice versa. 
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TABLE 23-2 



DNS Functions 


Function 


Description 


c hec kdn s r r ( $ h os t , [Stype]) 


Checks for existence of DNS records. Default is MX; other types 
are A, ANY, CNAME, NS, SOA, PTR and AAAA. Doesn't exist on 
Windows. 


gethostbyaddrdlpaddress) 


Gets hostname corresponding to address. 


gethostbyname($ hostname) 


Gets address corresponding to hostname. 


gethostbynamel (Shostname) 


Gets list of addresses corresponding to hostname. 


getmxrrt $hostname , [mxhosts 
array], [weight]) 


Checks for existence of MX records corresponding to hostname, 
places in mxhosts array, fills in weight info. This function doesn't 
exist on Windows. 



Socket functions 

A socket is a kind of dedicated connection that allows different programs (which may be on different 
machines) to communicate by sending text back and forth. PHP socket functions allow scripts to 
establish such connections to socket-based servers. For instance, web and database servers commu- 
nicate via fsockopen( ) — so you could theoretically write your own web server in PHP using this 
function, if you had lost all contact with reality. The connection can then be read from or written to 
with the standard file-writing functions (f puts ( ) , f gets ( ) , and so on.) 

The standard socket-opening function is fsockopen( ). The pfsockopen( ) function is identical 
except that sockets are not destroyed when your script exits; instead, the connection is pooled for 
later use. The blocking behavior of socket connections can be toggled with set_socket_bl ock- 
i ng ( ) . When blocking is enabled, functions that read from sockets will hang until there is some 
input to return; when it is disabled, such functions will return immediately if there is no input. 
These functions are summarized in Table 23-3. 



TABLE 23-3 



Socket Functions 

Function Description 

f sockopen ( $hostname , $port , Opens the socket connection to specified port on the host, 

[error number], [error string], and returns a file pointer suitable for use by functions like 

[timeout in seconds]) fgets(). 
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Function 


Description 


getservbyname($service, 
$protocol ) 


Returns the port number of the specified service. 


getservbyport ( $port , $protocol ) 


Returns service name on port. 


pf sockopen ( $hostname , $port, 
[error number], [error string], 
[timeout in seconds]) 


Opens the specified persistent socket connection. 


stream_set_bl ocking($socket 
descriptor, $mode) 


TRUE for blocking mode, FALSE for nonblocking. Default 
is nonblocking. 



Date and Time Functions 



These functions are basic tools used in many self-defined functions. You may use them simply to out- 
put the date or time, to keep track of microtime for a PHP performance-tracking utility, or to initiate a 
function over a particular date range (such as putting a Happy Ho 1 idays message on your site dur- 
ing holiday seasons). 

These are pretty straightforward to use if you understand the Unix timestamp. They fall into three 
main categories: functions that return date or time, functions that format date or time, and functions 
that validate date. 

The Unix timestamp measures time as a number of seconds since the beginning of the 
Unix epoch (midnight Greenwich Mean Time on January 1, 1970). Despite the name, 
these functions mostly work on Windows also. 

If you don't know either date or time 

The fastest way to get a time is to use the function timet ) . This will return the Unix timestamp 
for your locale, which will look something like 101906652. If you plan to pass this timestamp to 
another function or program, this is the best format. Alternatively, you can then use one of the 
functions in the next section to format the timestamp into something a bit more human-readable. 

You could also use m i c r o t i m e ( ) to return the current time in seconds and microseconds since the 
Unix epoch. This can be supremely helpful for utilities that are designed to measure performance. The 
format is 0.74321900 961906846, where the first part is microseconds and the second is the Unix 
timestamp. If you're trying to (for instance) measure the performance of different parts of your web 
page, you really just want the microseconds part, which can be cut out like this: 

<?php 

$stampmebaby = microtimeO; 

$chunks = explodet" ", $stampmebaby ) ; 
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$mi croseconds = $chunks[0] ; 

echo $mi croseconds; 

?> 

A function used to return date information is getdate($ti me stamp). When used with the argu- 
ment t i me ( ) , as in getda te ( ti me ( ) ) , it returns an associative array with the following numeric 
elements derived from the Unix timestamp: 

■ Seconds 

■ Minutes 

■ Hours 

■ Mday (day of the month, for example 1-31) 

■ Wday (day of the week, for example 1-7) 

■ Mon (month, for example 1-12) 

■ Year (numeric, for example 1984) 

■ Yday (day of the year, for example 1-365) 

■ Weekday (day of the week, for example Sunday-Saturday) 

■ Month (for example January-December) 

You can also use the getda te ( ) function with a Unix timestamp other than that representing the 
current time. 

If you want to get the time and format it in one step, you can use d a t e ( ) instead ofgetdate( ). In 
the absence of a Unix timestamp argument, d a t e ( ) will default to the current local date. This has 
the advantage of allowing nicer formatting, as we will explain in the next subsection. The function 
st rf ti me ( ) will also format the current Unix timestamp for you (as we explain in the next subsec- 
tion) unless another is specified. 

If you've already determined the 
date/time/timestamp 

The functions in this section come into play if you already have a timestamp and merely wish to 
format the information more finely. For instance, you may like to express your dates European style 
(2000.20.04) rather than American (4/20/2000). 

The main method to format a timestamp is using date($format. . .$formatn[, $timestamp]). 
You pass a series of codes indicating your formatting preferences, plus an optional timestamp. For 
instance: 

date( 'Y-m-d' ) ; 
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returns a string like 2002-05-27. You can choose a date with two-zero day identifiers or strictly 
numeric date identifiers, 12- or 24-hour format, or abbreviated month name. (See the PHP manual 
for all the options.) An analogous function is gmdate ( $f ormat . . . $f ormatn [ , $ti mestamp] ) , 
which will return a Greenwich Mean Date. 

The function strftime($format. . .$formatn[, $ti me stamp] ) is similar but specializes in 
formatting the time rather than the date; gmstrftime($format...$formatn [, $ti me stamp] ) 
returns the time in formatted Greenwich Mean Time. 

The function mkti me ( ) allows you to convert any date into a timestamp. It's subtly different in the 
order of arguments from the Unix command of the same name, so pay attention. The function gmm- 
kti me ( ) gives the Greenwich alternative to your own time zone. 

Finally, checkdate($month, $day, $year) allows you to quickly ensure that a particular date is 
a valid one. This is great for leap-year questions. 



Finally, we have some optional calendar conversion routines, which are now available as an extension. 

p j rj f Many new users have made the mistake of thinking calendar functions mean date func- 

tions. Not so. These functions strictly convert between different (largely historical) cal- 
endar systems. See "Date and Time Functions" earlier in this chapter if you feel you have entered this 
section in error. 

If you happen to be a French historian, you'll be happy to know that PHP can automatically convert 
between the French Revolutionary calendar and the Gregorian calendar with but a couple of com- 
mands. What can we say to that but: Bon Thermidor, citoyens et citoyennesl 

Seriously, these functions have real uses — particularly on the global Internet. (And not to be 
ungrateful or anti-Judeo-Christian-centric . . . but Joyce is patiently and lazily waiting for someone 
to add the Chinese lunar calendar to PHP, so she can always know when Chinese New Year celebra- 
tions will occur.) 

Conversion between systems is made possible because all the calendar functions share a universal 
referent, the so-called "Julian Day Number" (aka "Julian Day Count"). This is an integer that repre- 
sents the days since noon on the first of January, 4713 BC by the Julian calendar (which wasn't in 
use at the time, but why nitpick?). This date would be the 14th of January in the Gregorian calendar, 
which is commonly used in secular societies today. The so-called "Julian Date" is a double that rep- 
resents the days and hours since Julian Day Zero — but PHP does not allow this level of specificity; 
we're just mentioning it here in case anyone is looking for this information. 



Calendar Conversion Functions 




Remember that the Julian day changes at noon rather than midnight, which is the con- 
vention today. 
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PHP's calendar conversion functions translate a date in some calendar into or out of Julian Day 
Count. To convert between two calendars, you will need to use two separate functions: one to give 
the date from one calendar as a Julian Day Number, and the other to convert JD into another cal- 
endar's date. In this example, we are converting a Gregorian date into its equivalent in the Jewish 
calendar. 

$jd_no = gregori antojd(8 , 11, 1945); 
Shebrew = jdtojewi sh ( $ jd_no ) ; 
echo Shebrew; 

This will return a date of 2, 6 [Elul], 5705. Conversion to the Jewish calendar is somewhat 
complicated by the fact that it uses lunar months and its days begin at sunset rather than midnight. 

The calendars offered at the moment are: 

■ French Republican 

■ Gregorian 

■ Jewish 

■ Julian 

■ Unixian 

Each of these calendars has associated "JDToX" and an "XToJD" functions. 

Finally, there are two other pairs of miscellaneous calendar functions. JDMonthName( ) and 
JDDayofWeek( ) return the month and day of week of any Julian Day Number in any of the sup- 
ported calendars, whereas easter_date ( ) and easter_days ( ) will tell you when (Western 
or Catholic, as opposed to Eastern or Orthodox) Easter falls/fell/will fall in any given year, e a s - 
t e r_d a t e ( ) is the more straightforward method but can only be used within a Unix date range 
(1970-2037). It returns the Unix timestamp of Easter midnight in the specified year. 



Summary 

PHP has numerous filesystem and system functions built in, which can be extremely handy, 
although sometimes potentially insecure. A large number of PHP functions duplicate Unix systems 
utilities, such as chmod ( ) and copy ( ) . PHP can also boast some extra-clever functions such as 
those for DNS querying. Although we recommend turning off some of these functions, others can be 
useful in trusted hands and a well-planned environment. 

PHP's file opening, reading, and writing functions are extremely powerful tools. Most problems with 
these functions result from a slightly incorrect understanding of the file-opening modes. In addition 
to filesystem f open ( ) , PHP supports very slick HTTP, HTTPS, FTP, and standard I/O file opening. 

Finally, PHP offers a plethora of time, date, and calendar functions so you always know what time it is. 
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This chapter might as well have been called "Keeping Track," because 
its theme throughout is the problem of tracking interactions with 
users over longer periods of time than it takes to generate a single 
web page. We explain the extent of PHP support for extended user sessions 
and for setting and checking cookies, and then cover a couple of related 
techniques involving directly sending HTTP headers. 

Sessions and cookies are closely allied concepts in PHP and in web program- 
ming more generally, largely because the best way to actually implement ses- 
sions is by using cookies. Sessions are a higher-level concept than cookies, 
and for this chapter we plan to start at the top and work our way down. 



IN THIS CHAPTER 



Why do you need sessions? 

How PHP sessions are 
implemented 

Cookies and their use 

Sending HTTP headers with PHP 



What's a Session? 



What do we mean by a session? Informally, a session of web browsing is a 
period of time during which a particular person, while sitting at a particu- 
lar machine, views a number of different web pages in his or her browser 
program and then calls it quits, either for the night or because the person 
in question actually has a life. If you run a web site that this person visits 
during that time, for your purposes the session runs from that person's 
first download of a page from your site through the last. For example, a 
Caribbean hotel's web site might enjoy a session of five pages duration in 
the middle of a real user's session that began with a travel portal and ended 
with that user booking his or her vacation with a competitor. 
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So what's the problem? 

Why is the idea of a session tricky enough that we're just talking about it now, even though PHP is 
at version 6 already? It's because the HTTP protocol by which browsers talk to web servers is state- 
less, with the result that your web server has less long-term memory than your housecat. That is, 
your web server reacts independently to each individual request it receives and has no way to link 
requests together even if it is logging requests. If I sit at my computer in Chicago, and you sit at 
yours in Monterey, and we both ask for page one and then page two of the Caribbean hotelier's site, 
the HTTP protocol offers no help toward figuring out that two people looked at two pages each — 
what it sees is four individual requests for pages, with various information attached to each request. 
Not only does this information not identify you personally (by name, e-mail address, phone number, 
or any other traceable identification); it offers nothing reliable to identify your two page requests as 
being from the same person. 

Why should you care? 

If our web site's only mission in life is to offer various pages to various users, we may, in fact, not 
care at all where sessions begin and end. On the other hand, there are a number of reasons why we 
might in fact care. For example: 

■ We want to customize our users' experiences as they move through the site, in a way that 
depends on which (or how many) pages they have already seen. 

■ We want to display advertisements to the user, but we do not want to display a given ad 
more than once per session. 

■ We want the session to accumulate information about users' actions as they progress — as 
in an adventure game's tracking of points and weapons accumulated or an e-commerce 
site's shopping cart. 

■ We are interested in tracking how people navigate through our site in general — when they 
visit that interior page, is it because they bookmarked it, or did they get there all the way 
from the front page? 

For all of these purposes, we need to be able to match up page requests with the sessions they are 
part of, and for some purposes it would be nice to store some information in association with the 
session as it progresses. PHP sessions solve both of these problems for us. 



Home-grown Alternatives 

Before we look at PHP's treatment of sessions, let's look at a few alternative ways the problem can be 
handled. As you'll see, the PHP treatment combines a couple of these techniques. 
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IP address 

Web servers usually know either the Internet hostname or the IP address of the client that is requesting 
a page. In many configurations of PHP, these show up for free as variables — $_SERVER[ ' REM0TE_ 
HOST' ] and $_SERVER[ ' REMOTE_ADDR ' ], respectively. Now you might think that the identity of the 
machine at the other end is a reasonable stand-in for the person at the other end, at least over the short 
term. If you get two requests in quick succession from the same IP address, your code can safely con- 
clude that the same person followed a link or form from one of your site's pages to another. 

Unfortunately, the IP address your browser knows about may not belong to the machine your user 
is browsing from. In particular, AOL and other large operations employ proxy servers, which act as 
intermediaries. Your user's browser actually requests a URL from the proxy server, which in turn 
requests the page from your server and then forwards back the page to the user. The result is that 
many different AOL users might be browsing your site simultaneously, all apparently from the same 
address. IP addresses are not unique enough to form a basis for session tracking. 

Hidden variables 

Every HTTP request is dealt with independently, but each time your user moves from page to page 
within your site, it is usually via either a link or a form submission. If the very first page a user vis- 
its can somehow generate a unique label for that visit, every subsequent "handoff " of one page to 
another can pass that unique identifier along. 

For example, here is a hypothetical code fragment that you might include near the top of every page 
on your site: 

if (!IsSet($_GET['my_s_id'])) 

$my_sessi on_i d = generate_sess i on_i d ( ) ; 
// warning! hypothetical function 

This fragment checks to see if the $_G ET [ ' my_s_i d ' ] variable is bound — if it is, we assume that 
it has been already set and we are in the middle of a session. If it is not, we assume that we are the 
first page of a new session, and we call a hypothetical function called generate_sess i on_i d ( ) to 
create a unique identifier. 

After we have included the preceding code, we assume that we have a unique identifier for the ses- 
sion, and our only remaining responsibility is to pass it along to any page we link or submit to. 
Every link from our page should include the $my_s_i d as a GET argument, as in: 

<A HREF="next.php?my_s_id=<?php echo $_GET[ 'my_s_i d ' ] ; ?>">Next</A> 
And every form submission should have a hidden POST argument embedded in it, like this: 

<F0RM ACTION=next.php METH0D=P0ST> 
body of form 

<INPUT TYPE=HIDDEN NAME=my_s_i d 

VALUE="<?php echo $_GET[ ' my_s_i d ' ] ; ?> " > 

</F0RM> 
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What's wrong with this technique? Nothing. It works just fine as a way to keep different sessions 
straight (as long as you can generate unique identifiers). And once we have unique labels for the 
sessions, we can use a variety of techniques to associate other kinds of information with each ses- 
sion, such as using the session ID as a key for database storage. However, this approach to sessions 
is a pain to maintain — you must make sure that every link and form submission propagates the 
information as described, or the session identifier will be dropped. Also, if you send the information 
as GET arguments, your session-tracking machinery will be visible in the web-address box of your 
user's browser, and such arguments are easily edited by the user. Passing around unique identifiers 
in GET requests is probably the least secure method of maintaining state in web development, as well 
as possibly causing problems when your users try to cut and paste links — for instance, if they want 
to send a link to their friends via e-mail. 

Cookie-based home-grown sessions 

Another approach to session tracking is to use a unique session identifier as in the previous section 
but perform the handoff by setting or checking a cookie. 

A cookie is a special kind of file, located in the filesystem of your user's browsing computer, that 
web servers can read from and write to. Rather than checking for a passed GET/POST variable (and 
assigning a new identifier if none is found), your script checks the user's machine for a previously 
written cookie file and stores a new identifier in a new cookie file if none is found or if the old cookie 
has expired. This method has some benefits over using hidden variables: The mechanism works 
behind the scenes (typically, not showing any trace of its activity in the browser window), and the 
code that checks or sets the cookie can be centralized (rather than affecting every form and link). 

What's the drawback? Some very old browsers do not support cookies at all, and more recent brows- 
ers allow users to deny cookie-setting privileges to web servers. So, although cookies make for a 
smooth solution, we can't assume that they are always available. 

"r-fr ' I There is a subtle difference in the "coverage" of cookie-based sessions and that of sessions 
fc^"^^^™! based on GET/POST variables. A variable-based session will only maintain its identity as 
long as your user stays within your site, following intrasite links or form postings. However, there are any 
number of ways that a user might go away and come back again within a short period of time — by visit- 
ing a site that your site links to, which in turn links back or by wandering away and then finding your site 
again with a search engine. Cookie-based approaches will treat returns from these little detours as a con- 
tinuation of the same session, whereas variable-propagation approaches have to treat them as new visits. 

We cover cookies in more detail in the "Cookies" section later in the chapter. 



How Sessions Work in PHP 

Good session support takes care of the following two things: 

■ Session tracking (that is, detecting whether two separate script invocations are, in fact, part 
of the same user session). 

■ Storing information in association with a session. 
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Obviously, you need the first capability before you can hope to have the second. 

PHP session tracking works by a combination of the hidden-variables method and the cookie 
method described in the preceding section. Because of the advantages of cookies, PHP will use them 
when the user's browser supports them and, otherwise, will have recourse to stashing the session 
ID in GET and POST arguments. Fortunately, though, the session functions themselves operate at a 
more abstract level and take care of checking for cookie support all by themselves. If your version of 
PHP has been appropriately configured for sessions, you should be able to use the session functions 
without worrying which method is being used. 

p .- p f If you want PHP to transparently handle passing session variables for you when cookies 

~" ' ■' are not available, you need to have configured PHP with both the enabl e trans 
s i d and enabl e track vars options. If PHP is not handling this for you, you must arrange to 
pass a GET or POST argument, of the form sessi on_name=sess i on_i d, in all your links and forms. 
When a session is active, PHP provides a special constant, SID, which contains the right argument/value 
pair. Following is an example of including this constant in a link: 

<A HREF="my_next_page.php?<?php echo( S I D ) ; ?> " >Next page</A> 

Making PHP aware of your session 

The first step in a script that uses the session feature is to let PHP know that a session may already 
be in progress so that it can hook up to it and recover any associated information. This is done 
by calling the function sessi on_start( ), which takes no arguments. (If you want every script 
invocation to look for a session without having to call this function, set the variable session, 
a uto_sta rt to 1 in your php . i ni file, rather than the usual default of 0.) Also, any call to ses- 
si on_regi ster( ) causes an implicit initial call to sessi on_start( ). 

The effect of sess i on_sta rt ( ) depends on whether PHP can locate a previous session identifier, 
as supplied either by HTTP arguments or in a cookie. If one is found, the values of any previously 
registered session variables are recovered. If one is not found, then PHP assumes that we are in the 
first page of a new session, and generates a new session ID. 

Propagating session variables 

Changes in PHP's treatment of global and external variables starting with version 4.1 have made cer- 
tain things more inconvenient. In our view, though, these changes will also remove a lot of potential 
confusion about sessions. Accordingly, we'll list two approaches to propagating variables in sessions: 
one, which is simple and works in PHP version 4.1 or later, and another which is more complicated 
and works only in PHP version 4. 1 or earlier (unless you reenable the register_globals setting in 
php. i n i ) . (You can guess which one we recommend.) 

The simple approach (using $_SESSION) 

The simple approach is this: Assuming that you've made a call to sessi on_start( ) (as early in 
your script as possible), use the $_S ESS I ON superglobal array as your suitcase for storing any- 
thing that you want to retrieve again from a later page in the same session. Assume that any other 
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variables will be left behind when you leave this page and that everything in that suitcase will be 
there when you arrive at the next page. 

So, session code to propagate a single numerical variable can be as simple as this: 
<?php 

sessi on_start( ) ; 

$temporary_number = 45; 
$save_thi s_one = 19; 
$another_tempora ry = 33; 

$_S ESS ION [ ' save_thi s ' ] = $save_thi s_one ; 
?> 

The receiving code can be as simple as the following example: 
<?php 

sessi on_start( ) ; 

$saved_f rom_prev_page = $_S ES S 1 0 N [ ' save_thi s ' ] ; 
1. .] 

$temporary_number = 45; 
$another_tempora ry = 33; 
1. .] 
?> 

That's all there is to it. Assignment into the $_SESSI0N superglobal array implicitly does any regis- 
tration necessary for the new value to be carried forward to the next page. 

Note that we could have given the same name to both the variable ($save_thi s_one) and the cor- 
responding $_SESS ION index (save_thi s), because the two have nothing to do with one another. 

For this simple approach, we assume that register_globalshas been turned off (as it is by default in 
versions 4.2 and later), so that no session variables are being automatically promoted into global variables. 
Or, more precisely, we don't care whether it is turned on or not; the code will work in either situation. 

T^j 1 p' ' F The $ SESSION array is one of the superglobal variables introduced in PHP4.1. The 
superglobal adjective means that it can be referenced anywhere in PHP code, even 
within functions, without first being declared global. 

Where is the data really stored? 

There are two things that the session mechanism must hang onto: the session ID itself and any asso- 
ciated variable bindings. 

As you have seen, either the session ID is stored as a cookie on the browser's machine, or it is incor- 
porated into the GET/POST arguments submitted with page requests. In the latter case, there is really 
no storage happening — the ID is submitted as part of a request and is returned folded into HTML 
code for links and forms, which may generate the next request. The browser and server pass this vital 
information back and forth like a hot potato, and the session is effectively over if either side drops it. 



414 



Working with Cookies and Sessions 



24 



By default, the contents of session variables are stored in special files on the server, one file per 
session ID. (It's already slightly rude to store the session ID as a client-side cookie — it would be 
even more rude to store session variable data on the client disk when it's not necessary.) Doing this 
kind of storage requires the session code to serialize the data, which means turning it into a linear 
sequence of bytes that can be written to a file and read back to recreate the data. 

Obviously, storing session data on the server like this will cause problems in most clusters since 
each web server will be writing to files on its own (presumably unshared) disk. Unless your cluster- 
management scheme enforces all page views per session to be served from a particular host — which 
is uncommon, since in most cases that conflicts with the goals of load management and seamless 
failover — a new session will be started every time a page request is routed to a different server. 

There are three main methods to solve this issue, none of them easy or foolproof to implement. 
First, a company can write its own custom session-data-sharing layer. In this case, PHP will think 
it's making normal session-registration calls, but instead of writing to disk, a custom server will 
intercept the requests and centralize the data. However, developing and maintaining such a server 
and the customized version of PHP required is not cheap. Second, it's possible to direct PHP to write 
session data not to the normal local disk location (that is, /tmp) but to some other share which 
could be mounted by all web servers (such as / shared/session). This is the fastest solution if you 
have good sysadmins, since it requires only a change to the sessi on . save_path setting in php . 
i n i . Finally, it's possible to configure PHP to store the contents of session variables in a server-side 
database, rather than in files. This is probably the most common solution to the problem, although 
it should be kept in mind that this strategy will increase the impact of database failures. For more 
information, see the section "Configuration Issues" later in this chapter. 

r- y C/^C _[•* ' n * ne f' rst coition of this book, we warned you that serialization support for objects was 
wJ ~ J still problematic, and so we didn't recommend trying to store object variables in sessions. 

Fortunately, in PHP version 4.1 and later, session serialization seems to be stable. See Chapter 20 for 

more about object. 



Sample Session Code 

In Listing 24-1, we show a short code file, which really has a dual purpose. The first purpose is to 
provide an example of a full (short) script that successfully uses session functions; the second is to 
provide a test script that you can use to make sure that you have session support and that it is doing 
what you expect. 

In this listing, we perform the following tasks: 

■ Initiate a session (or pick up an existing one) by using sessi on_sta rt ( ) . 

■ Check for the existence of a preexisting entry in $_SESS ION. If one is not present, we 
assume that the session is new. 

■ Increment a counter that tracks how many times that the user has visited this page. 

■ Store the incremented counter back in $__SESS ION. 

■ Provide a link back to the page itself, embedding the session ID as an argument if it is found. 
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Test script using $_SESSION 

<?php 

sessi on_start( ) ; 
?> 

<HTMLXHEADXTITLE>Greetings</TITLEX/HEAD> 
<B0DY> 

<H2>Welcome to the Center for Content-free Hospi tal i ty</H2> 
<?php 

if (!IsSet($_SESSION['visit_count'])) { 

echo "Hello, you must have just arrived. 
Wei come!<BR>" ; 

$_SESSI0N[ 'visit_count' ] = 1; 



$self„url = $_SERVER[ ' PHP_SELF ' ] ; 
$session_id = SID; 
if ( I sSet ( $sess i on_i d ) && 
$session_id) ( 
$href = " $sel f_url ?$sess i on_i d" ; 

) 

else ( 

$href = $sel f_url ; 

} 

echo "<BRXA HREF=\ " $href \ " >Vi s i t us again</A> sometime"; 
?> 

</BODYX/HTML> 



This code should be available at www . t routwor ks .com/phpbook and is suitable for your use in 
testing your session support if you are using PHP4.1 or later. (See Listing 24-2, a little later in this 
section, if you are using a pre-4.1 version or if you prefer the regi ster_gl oba 1 s style of using ses- 
sions.) After obtaining the code, you should first simply test that it loads without errors. The page 
you see should look something like that shown in Figure 24-1. After that, to see if cookie-based ses- 
sion support is working, try simply reloading or refreshing the page in your browser. You should see 
a page that looks something like Figure 24-2. 



else ( 



$ v i si t_c o u n t = $ 
echo "Back again 



SESSION['visit_count'] + 1; 

are ya? That makes $visit„count times now 

anyone's counti ng )<BR> " ; 

count'] = $vi si t_count ; 



"(not that 



$_SESSI0N[ 'visit 
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FIGURE 24-1 



Session test page 



Greetings Morillii (Build ID: 2002051006] 



^ Elite Edit View Go Bookmarks Tools Window Help Debug QA 



Welcome to the Center for Content-free Hospitality 

Hello, you must have just arrived Welcome I 
Visit us aaam sometime 



Docnmenr: Done (0,43 sees} 



ME1 



J v hnp:tf192/l6B.1AfeesBionjea.php- "| [<\ Sflflfch ] \!ffi}l 



FIGURE 24-2 



Session test page, second visit 



Greelings Morillii [Build ID: 2002051006) 



, File Edrr View Go Bookmarks Tools Window Help Debug QA 



Welcome to the Center for Content-free Hospitality 

Back again are ya? That makes 2 times now (not that anyone's counting) 
Visit us afcarn sometime 



Dociimenr: Done 



TrTx] 



Q I v linp:«192.16B.1.T/segsion_1es1.php ~| [C^Samch | IM] 



If the result of your second visit is Figure 24-2, cookie-based session support is working. If instead 
it still looks like Figure 24-1, then PHP did not detect your session. Make sure that the browser 
you are testing with is configured to accept cookies and take a look at the section "Gotchas and 
Troubleshooting" at the end of this chapter. 

The second half of Listing 24-1 is about constructing a self-link that will propagate session informa- 
tion even without cookie support. You can test it by turning off cookies in your test browser. (This is 
usually an Advanced or Security option in your browser's preferences or options.) After cookies have 
been turned off, you should be treated as a first-time visitor when you reload the page. However, 
with cookies off, the SID constant should now contain the session ID name and value, which our 
code embeds in the link's URL as a GET argument. Clicking on this link should increment the visit 
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count appropriately, and thereafter either clicking the link or reloading should increment it again 
(because the session ID should now be in the URL that is being reloaded). 

This embedding of the session ID in the URL is exactly what should be unnecessary if PHP has been 
compiled with --enable-trans-sid. In this case, you should be able to add another self-link to 
this page, without embedding anything extra in the URL, and PHP should take care of it for you. 

Listing 24-2 shows the same test script as in Listing 24-1, except that it does not use superglobal 
variables and assumes that the regi ster_gl oba 1 s directive has been turned on. It's appropriate if 
you happen to be using PHP version 4.0.x, or if you prefer the regi ster_gl obal s style. Remember 
that code you write using regi ster_gl obal s will not be portable to many other PHP servers. 



LISTING 24-2 



Test script assuming register_globals 

<?php 

sessi on_start( ) ; 

session_register( ' visi t_count ' ) ; 
?> 



<HTMLXHEADXTITLE>Greetings</TITLEX/HEAD> 
<B0DY> 

<H2>Wel come to the Center for Content-free Hospi tal i ty</H2> 
<?php 

if ( ! IsSet( $vi si t_count ) ) ( 

echo "Hello, you must have just arrived. 
Wei come!<BR>" ; 

$ v i s i t_c o u n t = 1 ; 

1 

el se ( 

$vi sit_count++; 

echo "Back again are ya? That makes $visit_count times now ". 
"(not that anyone's counti ng )<BR> " ; 

} 



$self„url = $_SERVER[ ' PHP_SELF' ] ; 
$session_id = SID; 
if ( I sSet ( $sess i on_i d ) && 
$session_id) ( 
$href = " $sel f_url ?$sess i on_i d" ; 

1 

else ( 

$href = $sel f_url ; 

} 

echo "<BRXA HREF=\ " $href \ " >Vi s i t us again</A> sometime"; 
?> 

</BODYX/HTML> 
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Session Functions 

Table 24-1 lists the most important session-related functions, with descriptions of what they do. 
Note that in some cases the behavior of these functions depends on configuration options that we 
detail in the "Configuration Issues" section. 



TABLE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^HH 


Session Function Summary 


Function 


Behavior 


sessi on_ 
start ( ) 


Takes no arguments and causes PHP either to notice a session ID that has been passed 
to it (via a cookie or GET/POST) or to create a new session ID if none is found. 

If an old session ID is found, PHP retrieves the assignments of all variables that 
have been registered and makes those assigned variables available as regular global 
variables. 


sessi on_ 
regi ster( ) 


Takes a string as argument and registers the variable named by the string — for 
example, sessi on_regi ster( ' username ' ). (Note: The variable-name string 
should not include the leading $.) It can also be passed an array of string arguments 
to register multiple variables at once. Unnecessary if using $_SESSI0N or $HTTP_ 
SESSION_VARS. 

The effect of registering a variable is that subsequent assignments to that variable will 
be preserved for future sessions. (After a script completes, the registered variables and 
their values are serialized and propagated in such a way that later calls to sessi on_ 
Start () can recreate the bindings.) 

If sessi on_sta rt ( ) has not yet been called, sessi on_regi ster will implicitly 
call it before executing. 


sessi on_ 
unregister( ) 


Takes a string variable name as argument and unregisters the corresponding variable 
from the session. As a result, the variable binding will no longer be serialized and 
propagated to later pages. (The variable-name string should not include the leading $.) 
Unnecessary if using $_SESSI0N or $HTTP^SESSION_VARS. 


sessi on_i s_ 
regi steredC ) 


Takes a variable-name string and tests whether a variable with a given variable name is 
registered in the current session, returning TRUE if so and FALSE if not. Unnecessary if 
using $_SESSI0N or $HTTP_SESSION_VARS, use issetO instead. 


sessi on_ 
destroy ( ) 


Calling this function gets rid of all session variable information that has been stored. 
(Note: A browser's session ID may still be the same after this function call.) It does not 
unset any variables in the current script or the session cookie. 


sessi on_ 
unset ( ) 


Takes no arguments, and frees all variables in the session. Dangerous if using $_ 
SESSION or $HTTP_SESSION_VARS; use unset( ) instead. 



continued 
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1 TABLE 24-1 


1 (continued) 


Session Function Summary 


Function 


Behavior 


sessi on_ 
wri te_ 
cl ose ( ) 


Manually close session and release write lock on data file. Useful with frames, some 
clustering situations, and if you do something that might cause PHP to not realize the 
session has terminated (such as redirection). 


sessi on_ 
name( ) 


When called with no arguments, returns the current session-name string. This is 
usually ' PHPSESSID ' by default. 

When called with one string argument, sessi on_name ( ) sets the current session 
name to that string. This name is used as a key to find the session ID in cookies and 
GET/POST arguments — for successful retrieval, the session name must be the same 
as it was when the values were serialized and stored. Note that there is no reason 
to change the session name unless you have some need to distinguish session types 
that are being served by the same web server (such as in the case of multiple sites 
that each track sessions). The session name is reset to the default whenever a script 
executes, so any name change must happen in every script that uses the name, and 
before any other session functions are called. 


sessi on_ 
modul e_ 
name ( ) 


If given no arguments, returns the name of the module that is responsible for handling 
session data. This name currently defaults to 'files', meaning that session bindings 
are serialized and then written to files in the directory named by the function 

sessi on_sa ve_path ( ). 

If given a string argument, changes the module name to that string. (This could 
presumably be, for example, 'user 1 for a user-defined session database, but it should 
not be changed unless you know what you are doing.) 


sessi on_ 
save_path( ) 


Returns (or sets, if given an argument) the pathname of the directory to which session 
variable-binding files will be written (which typically defaults to / tmp on Unix 
systems). This directory needs to exist and have appropriate permissions for PHP to 
write files to it. On Windows systems, you must change this value to a valid path 
before using sessions! 


sessi on_i d( ) 


Takes no arguments and returns a string, which is the unique key corresponding to a 
particular session. If given a string argument, will set the session ID to that string. 


sessi on_ 

regenerate_ 

id() 


Takes no arguments and sets a new session ID, setting a new cookie if necessary and 
returning TRUE on success or FALSE on failure. Unlike ses s i on_i d ( ), it does not 
return a string with the actual new ID. 


sessi on_ 
encode ( ) 


Returns a string encoding of the state of the current session, suitable for use by 

s t r i ng_decode ( ) . This can be used for saving a session for revival at some later 

time, such as by writing the encoded string to a file or database. 


sessi on_ 
decode ( ) 


Takes a string encoding as produced by sessi on_en code ( ) and reestablishes the 
session state, turning session bindings into page bindings as sessi on_s t a rt ( ) does. 
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ses s i on_ Returns an array with current session cookie data: 1 i f et i me (in seconds till 

get_cookie_ expiration, or 0 for no expiration), path (for which the cookie is valid), domain (for 

pa rams ( ) which the cookie is valid), secure (whether or not the cookie will only be sent over 

SSL connections). These parameters are normally set in the php.ini file, but can be 
changed for a single script through the ses si on_set_cooki e_pa rams ( ) function. 

ses s i on_ Takes four arguments: int 1 i f eti me (in seconds till expiration, or 0 for no expiration), 

set_coo ki e_ string path (for which the cookie is valid), string doma i n (for which the cookie 

pa rams ( ) is valid), boolean secure (whether or not the cookie will only be sent over SSL 

connections). Be sure to include a trailing slash on the path argument. 



Configuration Issues 

The variables in Table 24-2 can be set in the php.ini file and viewable by calling p h p i n f o ( ) . We 
offer descriptions and the typical default values. (Some defaults are platform-dependent.) 



TABLE 24-2 



Session Configuration Variables 


Php.ini Variable 


Typical Value 


Description 


session. 
save_path 


/ tmp under Unix 
systems 


Pathname for the server-side directory where session datafiles 
will be written. Must be changed for Windows systems! 


session. 

a uto_sta rt 


0 


When 1, sessions will initialize automatically every time a 
script loads. When 0, no session data will be available unless 
there is an explicit call to either ses si on_sta rt ( ) or 
ses si on_regi ster( ). 


session. 
save_handl er 


'files', 'user' 


String that determines underlying method for saving session 
variable information. Changing this is not recommended for 
the casual user. 


session, 
c o o k i e_ 
1 i f eti me 


0 


Specifies how long session cookies take to expire and, 
consequently, the lifetime of a session. The default of 0 
means that sessions last until the browser is closed — any 
other value indicates the number of seconds the session is 
allowed to live. 



session.use_ 1 If 1, the session mechanism will attempt to propagate the 

cooki es session ID by setting/checking a cookie. (If the browser 

refuses the cookie, then GET/POST vars may be used.) If this 
variable is 0, no attempt to use cookies is made. 
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Cookies 

I '"' j^ ij£>^'- , I J ^ an ^ uses °^ cookies amount to session tracking — keeping track of some piece of infor- 
» ~~' J ~ J mation as a single user navigates through your site. If you are tempted to use cookies for 

a purpose like this, and you are using PHP4, you might want to consider simply using the built-in ses- 
sion functions that are covered in the section "Cookie-based home-grown sessions" earlier in this chap- 
ter. Not only do they offer a nicer level of abstraction, but they also have a built-in fallback mechanism 
that deals with refusal of cookies by propagating the information via GET/POST arguments instead. 

A cookie is a small piece of information that is retained on the client machine, either in the browser's 
application memory or as a small file written to the user's hard disk. It contains a name/value pair — 
setting a cookie means associating a value with a name and storing that pairing on the client side. Getting 
or reading a cookie means using the name to retrieve the value. (See the sidebar "Cookies and Privacy," a 
little later in this chapter, for a summary of the controversy surrounding the use of cookies.) 



NOTE 



As a general rule, you want to store information only in a client-side cookie when storing it 
on the server is not an option. This is partly simple politeness — try accepting cookies man- 
ually for a week, and you'll see some extreme abuses of the technique — but it is also because there are 
constraints that prevent server abuses of the client's hard disk. In particular, each browser will typically 
accept only 20 cookies from each domain before it starts popping old cookie values off the stack. If you 
need to store a lot of info, consider developing a scheme where the cookie file contains an ID that enables 
you to look up the rest of that information on the server — in other words, some form of sessions. 

In PHP, cookies are set using the setcookie( ) function, and cookies are read nearly automati- 
cally. In PHP4.1 and later, names and values of cookie variables show up in the superglobal array 
$_C00KI ES, with the cookie name as an index, and the value as the value it indexes. 



The setcookieO function 

There is just one cookie-related function, called setcooki e ( ) . Table 24-3 shows its arguments, in 
order, all but the first of which are optional. 



TABLE 24-3 



Arguments to setcookieO 


Argument Name 


Expected Type 


Meaning 


name 


string 


The name of your cookie (analogous to the name of a variable). 


val ue 


string 


The value you want to store in the cookie (analogous to the value 
you would assign to a variable). If this argument is not supplied, the 
cookie named by the first argument is deleted. 


expire 


int 


Specifies when this cookie should expire. A value of 0 (the default) 



means that it should last until the browser is closed. Any other 
integer is interpreted as an absolute time (as returned by the 
function mkti me ( )) when the cookie should expire. 
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Argument Name 


Expected Type 


Meaning 


path 


string 


In the default case, any page within the web root folder would 
see (and be able to set) this named cookie. Setting the path to a 
subdirectory (for example, "/forum/") allows distinguishing cookies 
that have the same name but are set by different sites or subareas of 
the web server (in this example, the cookie will only be valid in the 
forum area). Be sure to include a trailing slash in the path. 


httponl y 


boolean 


Cookies set with this flag are only sent through HTTP requests. 
Default is FALSE. 


domai n 


string 


In the default case, no check is made against the domain 
requested by the client. If this argument is nonempty, then the 
domain must match. For example, If the same server serves www . 
mysterygui de . com and f or urn . mysterygui de . com, one site's 
code can ensure that the other site does not read (or set) its cookies 
by including this argument as "forum . mysterygui de . com." 


secure 


boolean 
(TRUE (1) or 
FALSE (0)) 


Defaults to 0 ( FALSE). If this argument is 1 or TRUE, the 
cookie will only be sent over a secure socket (aka SSL or HTTPS) 
connection. Note that a secure connection must already be running 
for such a cookie to be set in the first place. 





rl. rV 






3kI 



For details about the representation of time used by the expi re argument, see Chapter 
23 — specifically, the discussions of the functions t i me ( ) and mkt i me ( ) 



Calling setcooki e( ) results in sending HTTP header information, which cannot be 
done after you have already sent some regular PHP output (even if that output consists of 
a single space or blank line!). 



Examples 

This section provides some example calls to setcooki e( ), along with comments, such as the 
following: 

setcookie( ' member name ' , ' ti mboy ' ) ; 

This sets a cookie called member name, with a value of ti mboy. Because there are no arguments 
except for the first two, the cookie will persist only until the current browser program is closed, 
and it will be read on subsequent page requests from this browser to this server, regardless of the 
domain name in the request or from where in the web root file hierarchy the page is served. The 
cookie will also be read regardless of whether the web connection is secure. For example, consider 
the following call: 

setcooki e( 'membername ' , 'troutgirl', timeO + (60 * 60 * 24), 
"/", "www.troutworks.com", 1); 
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This sets the cookie to have the value ' troutgi rl ' and would overwrite the previous example's 
value if it had been set by a previous page. The expiration time is set to 86,400 seconds (or 1 day) 
after the current time. The path argument is given the most inclusive path possible ("/"), so this 
cookie will still be read regardless of where it is in the web directory hierarchy. The host argument is 
set to ' www .troutworks.com', which means that subsequent page views will not cause the cookie 
to be read unless the user actually is making a request of that host. Finally, the last argument speci- 
fies that this cookie will only be read or written over a secure socket connection. (If the very con- 
nection used by this page is not secure, presumably the cookie will not be set at all.) 

~FTr r' f If you want to specify later arguments to set coo ki e ( ) while leaving the earlier ones 
^•n^^^W with their default values, it is best to give the empty string (" ") for the domain argument, 
a string containing a slash character ("/ ") for the path argument, and 0 for the expiration. 



Multiple calls to setcooki e( ) will typically be interpreted in the opposite order that 
they appear in your PHP script, although not every browser version does this. The best 
rule is to never send two different values for the same cookie from a single page execution. (Sending 
more than one is pointless anyway because one of them will always overwrite the other.) 



Cookies and Privacy 

Cookies have always been controversial from a privacy point of view, and that controversy heats up again 
periodically. As we wrote the first edition, Doubleclick (an Internet advertising agency) was being flamed for 
its announcement that it planned to cross-correlate cookie information with a very large database of consumer 
names, addresses, and buying habits (in an apparent reversal of earlier promises about such behavior). 

The worry was that, after a consumer reveals his or her identity on a site by filling out a form and accepting 
a cookie, any other site that compares notes with the original site could conceivably know the true identity 
of the user (and lots of other information as well). If this practice became widespread, every e-commerce site 
you visit might be able to figure out not only your name, address, and buying habits, but also a list of other 
pages you have visited on the web. 

So, cookies worry some people, but at the same time they are also a reasonable and benign workaround to the 
statelessness of the HTTP protocol. There are plenty of good reasons to want a web client/server interaction to 
coherently span a few page requests in a row, rather than covering just a single request. As a web developer, 
you might well decide to use cookies for such a purpose, comfortable in the knowledge that there is no sub- 
stantive invasion of privacy occurring. 

Your comfort is not the same as the user's comfort, however, and many users have set up their browsers to 
refuse all cookies, as is their right. (Remember that what is at issue here is not only the user's privacy but also 
the use of his or her own personal hard disk!) Any server-side code you write should gracefully handle a cookie 
refusal from the client side, and any web sites you design should have easily found privacy policies, so that 
your users know what they are getting into. This does not mean, though, that you are obligated to provide the 
same level of service to users that refuse cookies; there are some kinds of functionality that are just too painful 
to write without them, and deciding that cookie cooperation is a prerequisite to using a privately provided site 
seems perfectly legitimate. 
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Deleting cookies 

Deleting a cookie is easy. Simply call s e t c o o k i e ( ) , with the exact same arguments as when you 
set it, except the value, which should be set to an empty string. This does not set the cookie's value 
to an empty string — it actually removes the cookie. Remember: If you used the path or domain 
arguments to set the cookie, you need to use them to unset the cookie too. Another method to clear 
cookies is to set the expiration time in the past. 



Reading cookies 

Cookies that have been successfully set in a browser or user's machine will automatically be read on 
the next request from that browser. This has the following effects: 

■ In PHP4.1 and later, the cookie's name/value pair will be added to the superglobal array 
$_C00KI E, as though we had evaluated $_C00KI E[ 'name'] = value. 

■ If the regi ster_gl obal s directive is turned on (for versions earlier than PHP6), a regular 
page-level global variable will be set to the cookie's value, named the same as the cookie's 
name. Because regi ster_gl obal s is turned off by default starting with PHP4.2, this 
feature is not available in 4.2 or later, unless either you or your ISP's administrator has 
changed the configuration. 



So, for example, you can set a cookie as follows: 

setcookie( ' member name ' , ' ti mboy ' ) ; 



This means that, on a later page access, you might be able to print the value again as easily as this: 

$membername = $_C00KI E [ ' membername ' ] ; 
print("The member name is $membername<BR>" ) ; 

And, if regi ste r_gl oba 1 s has been turned on, the later page's use of the cookie becomes 
even simpler: 

print("The member name is $membername<BR>" ) ; 



\-UUsT— 



If you set a cookie in a given script, it won't be set on the client until that page (and 
its HTTP headers) are sent off to the client, which is too late for you to be able to take 
advantage of it in that very script. This means that the corresponding global variable won't be available 
to you until the next page request. 



The following code typically does not work as you might expect: 
setcookie( ' membername ' , ' ti mboy ' ) ; 

printC'I set a cookie! Now I will grab the value<BR>"); 

// (WRONG - the following membername will most likely be blank; 

$membername = $_C00KI E[ ' membername '] ; 

print("The member name is $membername<BR>" ) ; 
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This is because, as the preceding note points out, the cookie will not be set until the current page's 
worth of HTTP headers arrives at the client. Because that has not yet happened in this example, and 
the variable $membername has not been otherwise set, that variable will probably produce an empty 
string in the preceding print statement. 

The following code gets it right: 

$cookievalue = 'timboy'; 

setcookie( 'membername' , $cookievalue) ; 

printC'I set a cookie for the benefit of future pages<BR>"); 
// (RIGHT - only print variables that this page actually set) 
print("Its name is membername, its value is $cookieval ue<BR>" ) ; 

Any subsequent scripts that are loaded into the same browser can now refer to $membername. 

f'r^ rjCJ^L J"-*- p_p ^ e nave a ' rea dy noted some privacy risks to users of accepting cookies from servers. 

~' J ~ ""^ J •* J "' It's worth noting that there are risks that go the other way as well. If you write scripts 
that depend on the integrity of data that you include in cookies, you should remember that a clever 
end user can edit those cookies and install arbitrary values in them. See Chapter 28 for techniques for 
encrypting sensitive data, even inside cookies. 

Cookie pitfalls 

It is hard to do much wrong with cookies purely at the PHP level. After all, setting a cookie involves 
only one function (set_cookie( )), and reading cookies involves no functions at all. What could be 
easier than that? The problems that typically arise are those imposed by the HTTP protocol itself. 

Sending something else first 

The single most common error in using cookies is trying to set a cookie after some regular HTML 
content has already been generated. (We may be repeating ourselves here, but we will also repeat it 
in the "Sending HTTP Headers" section later in the chapter, because this fact applies to other direct 
HTTP protocol manipulations in addition to cookies and is the cause of a great deal of debugging 
confusion.) 

The reason this doesn't work is that the HTTP protocol requires headers to be sent before the con- 
tent of the HTML page itself — they can't be intermixed. As soon as any regular content is gener- 
ated, PHP figures that it must already know about all headers of interest, and so it sends them off 
and then begins the transmission of HTML content. If it encounters a cookie (or other header infor- 
mation) later on, it is too late, and an error is generated. 

It's surprisingly easy to write code that violates this prohibition. Consider the following: 

<?php /* A subtle, insidious cookie error */ 
setcookie( 'my cookie' , 'my value' ); 
?> 

<HTMLXHEAD> 

<TITLE>A seemingly benign cookie-setting page</TITLE> 
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</HEADXBODY> 

<H3>This page is so simple it absolutely must be right</H3> 
</BODYX/HTML> 

When we load this script, we get browser output indicating cannot add header information. 
The culprit is the very first character in the file: the space before <?php. Because PHP files start off 
in HTML mode by default, this file causes one space's worth of generated content to be sent to the 
client before PHP mode kicks in, and the attempt is made to set the cookie. 

A similar way to accidentally send header information too early is to i n c 1 u d e ( ) or r e q u i r e ( ) a file 
that includes blank lines at the end after the closing PHP tag. Finally, of course, you can violate the 
prohibition entirely in PHP mode, but only if you include something like aprintorecho statement. 

If you ever run into this kind of error, it is relatively easy to debug if you are methodical about it. Try 
moving HTTP-related code toward the beginning of the script file first — if you still get the error 
after that, then trace backward from the offending line toward the beginning of the file. Somewhere 
between the beginning and the failing statement you either have some characters that are being 
interpreted in HTML mode, or else you have a PHP printing construct. If you have any included 
PHP files before the offending statement, make sure that there are no characters at all before the start 
tags or after the end tags. 

Reverse-order interpretation 

As with most HTTP commands, calls to setcooki e() may actually be executed in the opposite 
order from the way that they appear in your PHP script, but this depends on the particular browser 
your user is running and the version of PHP you're using. This means that a pair of successive state- 
ments like the following probably have the counterintutive result of leaving the " my c o o k i e " cookie 
with no value, because the unsetting statement is executed second. 

setcookiet" my cookie");// get rid of the old value (WRONG) 
setcooki e( "mycooki e" , "newval ue" ) ; // set the new value (WRONG) 

pTTj - ^ f There is no need to remove a cookie before setting it to a different value — simply set 
it to the desired new value. Among other things, this means that the confusing reverse 
order of interpretation of setcooki e ( ) calls should not usually matter — if the effect depends on the 
order, it may mean that you are doing something wrong (or at least something unnecessary). 

Cookie refusal 

Finally, be aware that setcooki e( ) makes no guarantees that any cookie data will, in fact, be 
accepted by the client browser — setcooki e() just agrees to try, by sending off the appropriate 
HTTP headers. What happens after that is up to the client, and the client may be an older browser 
that does not accept cookies or a browser whose user has intentionally disabled cookies. 

The setcooki e( ) function does not even return a value that indicates acceptance or refusal of 
the cookie. If you think about it, this is imposed by the timing of the script execution and the 
HTTP protocol. First, the script executes (including the setcookie( ) call), with the result that a 
page complete with HTTP headers is sent to the client machine. At this point, the client browser 
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decides how to react to the cookie-setting attempt. Not until the client generates another request 
can the server receive the cookie's value and detect whether the cookie-setting attempt was success- 
ful. The implication of this for scripting is that you must always ensure that something reasonable 
happens, even in cases where setcookie( ) is called without success. One common technique 
is to set a test cookie with the name CookiesOn and then check on a subsequent page load if the 
$_C00KI E ['CookiesOn'] variable has been set. 



Sending HTTP Headers 



The setcookie( ) call provides a wrapper around a particular usage of HTTP headers. In addition, 
PHP offers the h e a d e r ( ) function, which you can use to send raw, arbitrary HTTP headers. You can 
use this function to roll your own cookie function if you like, but you can also use it to take advan- 
tage of any other kind of header-controlled functionality. 

The syntax of header () is as simple as it can be: It takes a single string argument, which is the 
header to be sent. 



r- , 



- |"7v . i\ ' All the cautions from earlier in this chapter (about sending HTTP before any real page 
"■• ■ content) apply to the header ( ) function as well. 



Example: Redirection 

One useful kind of HTTP header is " Locati on : ", which can act as a redirector. Simply put a fully 
qualified URL after the "Location:" string, and the browser will start over again with the new 
address instead. Here's an example: 

<?php 

if (IsSet($_GET['gender']) && ( $_GET[ ' gender ' ] == "female")) 
{ 

header ( 

"Location: http: //www .example.com/secret.php") ; 
exi t ; 

} 

?> 

<HTMLXHEADXTITLE>The inclusive page</TITLEX/HEADX/HTML> 
<B0DY> 

<H3>Welcome!</H3> 

We welcome anyone to this page, even men! Talk amongst yourselves. 
</BODYX/HTML> 



If we simply enter the URL for this page (www . example. com /inclusive.php), we will see the 
rendering of the HTML at the bottom of the script. On the other hand, if we include the right GET 
argument (www . ex ample. com/ inclusive. php?gender=female), we find ourselves redirected to 
a different page entirely. Note that this is significantly different from selectively importing contents 
with the i n c 1 u d e ( ) statement — we actually end up browsing a different URL than the one we 
typed in, and that new web address is what shows up in the Location or Address bar of your browser. 
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This kind of redirection can be useful when you want the structure of your web site to conditionally 
branch without having to make the user explicitly choose different links. 



Example: HTTP authentication 



Another useful thing you can do with HTTP is ask the browser to ask the user for a username and 
password, via a pop-up window. This is done with the WWW-Authenti cate header, as in the follow- 
ing example: 

<?php 

$the_ri ght_user = 'user'; // example only! not recommended 
$the_ri ght_password = 'password'; // example only! 

if ( !isset($_SERVER[ ' PHP_AUTH_USER ' ] ) ) ( 

Header( "WWW-Authenti cate: Basic realm=\"PHP book\""); 

Header( "HTTP/1 .0 401 Unauthorized"); 

echo "Canceled by user\n"; 

exi t ; 
I else ( 

if (($_SERVER['PHP_AUTH_USER'] == 'user') && 

($_SERVER[ ' PHP_AUTH_PW' ] == 'password')) //see caution below 
print("The realm is yours<BR>"); 
else 

print("We don't need your kind<BR>"); 

} 

?> 

If we visit this script for the first time (and are using the appropriate browser and server versions), 
we will get a pop-up window. After the user enters the information into the pop-up box, the script 
is automatically called again with new variables $„SERVER[ ' PHP_AUTH_USER ' ] (set to the user 
string entered), $_SERVER[ ' PHP_AUTH_PASSWD ' ] (set to the password string entered), and $_ 
SERVER! ' PHP_AUTH_TY PE ' ] (which will be Basic until such time as another type of authentication 
is supported). The nice thing about this is that these variables will continue to be set by the browser 
on each request, and you do not need to do anything in your scripts to propagate them — one verifi- 
cation of identity per session should suffice. 



CAUTION 



The preceding code is the bare minimum necessary to demonstrate the HTTP authentica- 
tion mechanism and is not a model for how user/password combinations should really 
be verified! Our code fragment simply compares the values of the variables delivered to hardcoded 
strings, which is a bad idea for several reasons. To make this part of a real verification system, you 
probably want to compare the result of encrypting the password to a similarly encrypted version in a 
database or password file. See Chapter 28 for more on encryption and real security measures. 

In addition to redirection and authentication, the capability to send real HTTP headers offers finer 
control of many aspects of the HTTP client/server relationship, which usually are set by default. For 
example, you can explicitly set the expiration and caching behavior of your page, or send return 
status codes that tell the client whether whatever is returned should be considered a success or not. 
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Because PHP is just acting as a channel to the underlying HTTP protocol, most of these techniques 
are beyond the scope of PHP documentation and this book. 



NOTE 



The WWW Authenti cate mechanism works only under the Apache Web Server, with 
PHP as a module. It does not currently work in the CGI version or under IIS/PWS. 



Header gotchas 

As we have said innumerable times by now, the h e a d e r ( ) function is subject to the same restric- 
tion as the setcooki e ( ) function: No headers may be sent after regular page content is generated, 
unless you are using a release of PHP that has output buffering enabled. 

More generally, be aware that using the header capability requires not only some knowledge of the 
HTTP protocols but also some knowledge of the extent to which different browser versions conform 
to them. Unless you are writing for a known population of users that all use the same browser, you 
will probably need to do more cross-browser testing than with vanilla HTML-generating scripts. 

j^jp - ^ i Most browsers can be set to warn you whenever they are about to accept a cookie. 
■"™^^^^™< Although this can be annoying when viewing benign yet cookie-intensive sites, it can also 
be a great debugging tool when writing your own cookie-setting code. Mozilla browsers also feature a 
tool called Cookie Manager that lists cookies from each site and allows you to manually delete them, 
which is also handy for debugging. 



Gotchas and Troubleshooting 

If you are having trouble with sessions, first make sure that your session support exists and is doing 
what you think it is. Try downloading the sample session code from www .troutworks.com/ 
phpbook and debugging it from the earliest error, if any. 

If sessions are not working or are giving errors, check the pathname returned by s e s s i o n_s a v e_ 
p a t h ( ) , and make sure that it exists and is PHP writable. If not, you should either make it so or 
change the value of 'session, s a v e_p a t h ' inphp.ini. 

Remember that session functions that have variable names as arguments do not expect a leading $ 
in the name. 

If you ever run into a complaint that refers to already having sent HTTP headers, it may be that your 
script is sending some text (even blank lines) before the s e s s i o n_s t a r t ( ) or session_regis- 
ter ( ) functions. Scrutinize any included files for blank lines or move the session functions to the 
very beginning of your file. 

When testing session-related code, remember to try it out both with a browser that accepts cook- 
ies and with a browser that is set up to refuse them. If you see no session name in the URL of a link 
(such as, 'PHPSESSID') with a cookie-refusing browser, then either sessions are not working or 
your version of PHP is not configured to transparently pass session IDs in the G ET/POST arguments. 
It's also informative to try session and cookie code with a browser that is configured to alert the user 
whenever it is setting a cookie. 
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Summary 

Sessions are useful for tracking a user's behavior over interactions that last longer than one script 
execution or page download. If what you present to the user depends on which previous pages he 
or she has seen or interacted with, your code must store or propagate that information in a way that 
distinguishes one user from another. Because the HTTP protocol is stateless, this inevitably entails 
some kind of workaround technique — usually either hidden variables (which impose maintenance 
headaches) or cookies (which are not universally supported by client browsers). 

The PHP implementation of sessions encapsulates these messy issues and presents a clean layer of 
abstraction to the scripter. Unique session identifiers are automatically created and propagated, and 
variables can be passed from page to page by storing them in the superglobal $„S ESS I ON array. 
Aside from one's having to connect to a session initially and store (or register) the variables that 
should persist beyond the current page, session use is virtually transparent to the programmer. 

PHP offers several ways to use the capabilities of the HTTP protocol, in addition to the obvious one 
of constructing HTML pages that are transmitted via HTTP. The setcookie( ) function allows you 
to set and delete cookies in your user's browser, the values of which show up in subsequent page 
views as ordinary global variables. 

The h e a d e r ( ) function allows you to send arbitrary HTTP headers. Among other things, h e a d e r ( ) 
can be useful for authentication and page-level redirection. 

The HTTP functions in PHP are very simple, and the main complexities that arise are a consequence 
of the HTTP protocol itself. One such complication is the fact that that HTTP requires all headers 
to be sent before any page content is sent. Remember that any use of header-manipulating functions 
must happen before even a blank space is sent to the browser. 
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In Chapter 4, we covered PHP types in basic terms, outlining the dif- 
ferent types and how they might best be used in your programs. Our 
first purpose in this chapter is to review those types and elaborate a 
little more on resources. (Another type, objects, was covered fully in Chapter 
20.) We'll also look at some type-testing techniques, and finally, type 



conversion. 



Type Round-up 



You should remember from earlier chapters that unlike many other lan- 
guages, PHP does not require explicit type declarations. PHP is fairly intui- 
tive about the purpose of your various variables and can often infer your 
intent from the context in which those variables are used. PHP, for example, 
understands that the statement: 

$my_value = 4.50; 

refers to a float, that is, a floating-point number. But if you subsequently 
create a string, such as: 

$my_string = "I paid \$$my_value for a box of 
twi n ki es . " ; 

PHP understands that it needs to convert the variable $my_va1 ue into 
a string for purposes of concatenating the larger string assigned to 
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the variable $my„stri ng. However, this conversion should in no way prevent you from later 
doing something like: 

$my_tax = .065; 
$my_total = round( $my_val ue + 
$my_string .= "However; if I 1 
Twinkies are not considered a 
would have cost 
\$$my_total " ; 

The eight basic PHP types are listed here. If you need more of a reminder, refer to Chapter 4. The 
more complex types are treated in their own chapters: strings in Chapter 7, arrays in Chapter 8, and 
objects in Chapter 20. 

■ Integers are whole numbers, without a decimal point, like 495. 

■ Floats (aka doubles) are floating-point numbers, like 3.14159, or 49.0. 

■ Booleans have only two possible values: TRUE and FALSE. 

■ NULL is a special type that has only one value: NULL. 

■ Strings are sequences of characters, like ' PHP4 . 0 supports string operations'. 

■ Arrays are named and indexed collections of other values. 

■ Objects are instances of programmer-defined classes, which can package up both other 
kinds of values and functions that are specific to the class. 

■ Resources are special variables that hold references to resources external to PHP (such as 
database connections). 



Resources 

As previous chapters provided in-depth coverage of the first seven types, let's have a look at the 
eighth. Resources are special values that refer to memory or state information that is external to the 
PHP language itself. You don't have to know too much about resources for casual PHP program- 
ming — we'll briefly explain what resources are all about, but feel free to skip to the section "How to 
handle resources." 

What are resources? 

The resource type is needed when PHP communicates with some external program (which may be a 
database or a graphics program) that allocates memory in response to requests from PHP. In general, 
PHP programmers do not have to worry about freeing memory within PHP — if you create a string 
in a PHP script (which will take up some space in memory), you can forget all about it and let your 



($my_value * $my_tax)); 
ived in a state where 
food item, the same box 
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script run until the end. PHP (or the web server it is attached to) will reclaim all memory associated 
with your script when your script is done, if not earlier. 

External programs (databases, and so on.) might not be smart enough to do this deallocation. You 
might have space reserved in your database's memory for your script long after your script has gone 
to script heaven. The way this problem gets handled in PHP is that all special functions that request 
memory from such external programs return resources, which PHP tracks to see if your script can 
still get to them. If nobody can reach the resource, PHP makes sure that the external program does 
the right kind of cleanup. PHP does this by counting references to the resource — if the reference 
count goes to zero, then the resource can be freed. 

How to handle resources 

In general, PHP programmers do not create resources by themselves — they call special func- 
tions that return values of the resource type, and then pass them on to other functions that require 
resources. For example, you might call the function mysql_connect( ) (which returns a resource 
value that refers to a connection to a MySQL database), save the result in a variable, and then pass it 
on to my s q 1 _q u e ry ( ) (which uses the connection resource to query the database). 

Essentially, all you have to do with this connection resource is store it in a variable and pass that 
variable to functions that require it. You can depend on PHP to clean up the resource after your 
script is done. If, for whatever reason, you feel that the resource is tying up enough memory during 
script execution that you want the memory freed before the script is done, you can usually do some- 
thing like this: 

$my_resource = mysql _connect ( ) ; // stores variable 

// .. code that uses the connection resource .. 

$my_resource = NULL; // variable no longer refers to resource 

The reassignment of $my_resource should cause PHP to check that no other piece of code is using 
the MySQL resource and then free it. Alternatively, most resource-opening functions have resource 
closing counterparts such as my s q 1 _c 1 o s e ( ) , covered in Chapter 15, or f c 1 o s e ( ) , which we used 
in Chapter 23. 



Type Testing 

Especially because variables can change types because of reassignment, it is sometimes necessary to 
find out the type of a value at program execution time. PHP offers both a general type-testing func- 
tion (getty pe ( )) and individual Boolean functions for each of the five types. These functions, some 
of which have alternate names, are summarized in Table 25-1. 
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TABLE 25-1 



Functions for Type Testing 


Function 


Behavior 


gettype ( a rg ) 


Returns a string representing the type of a rg: either integer, float, string, array, 
object, or unknown type 


i s_ 


_i nt ( a rg ) 


Returns TRUE if a rg is an integer, and FALSE if not 


i s_ 


_i n t ege r ( a r g ) 




i s 


1 ong ( a rg ) 




i s 


doubl e ( a rg ) 


Returns TRUE if arg is afloat, and FALSE if not 


i s_ 


_f 1 oat ( a rg ) 




i s_ 


_real (arg) 




i s_ 


_bool (arg) 


Returns TRUE if arg is a Boolean value (TRUE or FALSE), and FALSE if not 


i s_ 


_nul 1 (arg) 


Returns TRUE if arg is of the NULL type, and FALSE if not 


i s_ 


_st r i ng ( a rg ) 


Returns TRUE if arg is a string, and FALSE if not 


i s_ 


_array(arg) 


Returns TRUE if arg is an array, and FALSE if not 


i s_ 


_ob j ect ( arg ) 


Returns TRUE if arg is an object, and FALSE if not 


i s_ 


^resource ( arg) 


Returns TRUE if arg is a resource, and FALSE if not 


i s_ 


_bi na ry ( a rg ) 


Returns TRUE is arg isa binary string, and FALSE if not 


i s_ 


_buf f er ( arg ) 


Returns TRUE is a rg is a Unicode or binary string, and FALSE if not 


i s_ 


_scal ar(arg) 


Returns TRUEisargisa scalar variable, and FALSE if not 


i s_ 


_uni code ( arg ) 


Returns TRUE is a rg is a Unicode string, and FALSE if not 


i s_ 


_numeri c ( a rg ) 


Returns TRUE is arg is numeric, and FALSE if not 



Assignment and Coercion 

As we have said, PHP often automatically converts from one type to another when the context 
demands it, and as it turns out, the PHP programmer can also force some of these conversions to 
happen. In either situation, the programmer should know what to expect. 

Type conversion behavior 

Here are some general rules for PHP's conversion from one type to another: 

■ Integer to float: The exact corresponding float is created (for example, the i nt 4 becomes 
the float 4.0). 
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■ Float to integer: The fractional part is dropped, truncating the number toward zero. 

■ Number to Boolean: FALSE if exactly equal to 0, TRUE otherwise. 

■ Number to string: A string is created that looks exactly the way the number would print. 
Integers are printed as a sequence of digits, and floats are printed with the minimum preci- 
sion needed. Extreme float values will be converted to scientific notation. 

■ Boolean to number: 1 if TRUE, 0 if FALSE. 

■ Boolean to string: ' 1 ' if TRUE, the empty string if FALSE. 

■ Null to number: 0. 

■ Null to boolean: FALSE. 

■ String to number: Equivalent to reading a number from the string, then making a conver- 
sion to the given type. If a number cannot be read, the value is zero. Not all of the string 
needs to be read for the reading to be considered a success. 

■ String to Boolean: FALSE if it is an empty string or the string is ' 0 ' , T R U E otherwise. 

■ Simple type (number or string) to array: Equivalent to creating a new array with the 
simple value assigned to index zero. 

■ Array to number: Undefined (see following note). 

■ Array to Boolean: FALSE if the array has no elements, TRUE otherwise. 

■ Array to string: 'Array'. 

■ Object to number: Undefined (see note below). 

■ Object to boolean: TRUE if the object contains any member variables that have a value, 
and FALSE otherwise. 

■ Object to string: ' Object ' . 

■ Resource to Boolean: FALSE. 

■ Resource to number: Undefined (see note below). 

■ Resource to string: Something like ' Resource id #1 ' (but this should not be relied upon). 

In the preceding list, we noted that some types have an undefined result when converted to numeri- 
cal values. In this context, undefined simply means that the PHP developers are not making a com- 
mitment as to what kind of behavior you'll get in future versions of PHP, so it would be a bad idea 
to depend on a particular behavior in your code. You may find that these types can be converted to 
numbers in expressions in your particular version of PHP, but that may not work in the next version. 

Explicit conversions 

PHP offers three different ways for the programmer to manipulate types: conversion functions, type 
casts (as in the C language), and calling settype ( ) on variables: 

■ The functions intval ( ), floatval ( ), and s t r v a 1 ( ) will convert their arguments to 
an integer, a float, or a string, respectively. (At this writing, there does not seem to be a 
bool va 1 ( ) function.) 
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■ Any expression can be preceded by a type cast (the name of the type in parentheses), 
which converts the expression result to the desired type. 

■ Any variable can be given as a first argument to s etty pe ( ) , which will change the type of 
that variable to the type named in the second string argument. 

For example, each of the following approaches will put the correct count of canines (101) into the 
integer variable $ d o g_c o u n t by the end of the code snippet: 

Version #1: 

$dog_count = intval (strval ( f 1 oatval ( " 101 Dalmatians"))); 
Version #2: 

$dog_count = (int) (string) (float) "101 Dalmatians"; 
Version #3: 

settype ( $dog_count , "float"); 
set type ( $dog_count , "string"); 
settype ( $dog_count , "int"); 

'-> | >j™ I Of course, each approach in the example takes an indirect route, converting needlessly 
I - - ■ to string and float types — it would suffice to convert immediately to the integer type. 

Six of the basic type names (integer, float, boolean, string, array, and object) are valid in casts and 
are valid string arguments to settype ( ) . In addition, certain alternate names are valid in casts: 
(i nt) instead of (i nteger), (double) or (re a 1 ) instead of (f 1 oat), and (bool ) instead of (boo 1 - 
ean). It is not valid to cast to type resource, and casting to type NU LL is pointless. (Because the 
result can only be the value NULL, you might as well simply assign instead.) 

Conversion examples 

Listing 25-1 shows some PHP code that displays various type conversions in an HTML table, with 
the resulting table shown in Figure 25-1. (This code is not intended as a style example, and it uses 
several constructs that have not yet been covered — feel free to just look at the output.) 



LISTING 25-1 



Type conversions 

$type„exampl es [0] = 123; // an integer 

$type_exampl es[l] = 3.14159; // a float 

$type_exampl es [2] = "a non-numeric string"; 

$type_exampl es [3] = "49.990 (begins with number)"; 

$type_exampl es[4] = a r ray ( 90 , 80 , 70 ) ; 

pri nt( "<TABLE B0RDER=1XTR> " ) ; 
print ( "<TH>0riginal</<TH>") ; 
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print("<THXint)</<TH>") ; 
print("<THXfloat)</<TH>") ; 
print ("<THXstringX/<TH>" ) ; 
print ( "<TH>( array )</<THX/TR>" ) ; 

for ($index = 0; Sindex < 5; $index++) 
{ 

pri nt( "<TRXTD>$type_exampl es [ $i ndex] </TD> " ) ; 
$converted_var = 

(int) $type_exampl es [ $ i ndex] ; 
pri nt( "<TD>$converted_var</TD>" ) ; 
$converted_var = 

(float) $type_exampl es [ $i ndex] ; 
pri nt( "<TD>$converted_var</TD>" ) ; 
$converted_var = 

(string) $type_exampl es[$ index] ; 
pri nt( "<TD>$converted_var</TD>" ) ; 
$converted_var = 

(array) $type_exampl es [ $i ndex] ; 
print( "<TD>$converted_var</TDX/TR>" ) ; 

} 

pri nt ( " </TAB LE> " ) ; 



FIGURE 25-1 
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Other useful type conversions 

The functions listed in Table 25-2 do not exactly convert types, but they return a different type from 
their main argument in a useful way. 



TABLE 25-2 



Other Type Conversion Functions 


FromYTo 


Integer String 


Array 


Integer 


ord ( ) 




Float 


cei 1 ( ) , f 1 oor( ) , 
round ( ) 




String 


chrO 


expl ode ( ) 


Array 


i mpl ode ( ) 





The function cei 1 ( ) takes a float and returns the integer greater than or equal to that float. 
For example: 

$my_float =4.7; 

$my_int = cei 1 ( $my_f 1 oat ) ; // $my_int is equal to 5 

$my_float = -4.7; 

$my_int = cei 1 ( $my_f 1 oat ) ; // $my_int is equal to -4 

The f 1 oo r ( ) function is the opposite of cei 1 ( ) . (We'll drop the intermediate assignment to $my_ 
float now.) 

$my_int = floor (4.7); // $my_int is equal to 4 
$my_int = f 1 oor( -4 . 7 ) ; // $my„int is equal to -5 

The r o u n d ( ) function takes a float and returns the nearest integer. If the fractional part of the float 
is exactly one half, the rounding is to the highest absolute number. 

$my_int = round(4.7); // $my_int is equal to 5 
$my_int = round(-4.7); // $my„int is equal to -5 
$my_int = round(-4.5); // $my„int is equal to -5 

If you're looking for a truncate function (simply dropping the fractional part and, therefore, 
rounding toward zero), notice that this is the behavior you get simply from typecasting 
from f 1 oat to i nt. 
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The function c h r ( ) takes an integer and returns a one-character string with that ASCII value, 
whereas o r d ( ) reverses this, returning the ASCII value of the first character in a string. 

Finally, i mpl ode ( ) and expl ode ( ) allow a certain kind of conversion between strings and arrays, 
i mpl ode ( ) creates a string from the array it is given as second argument, separating the elements 
with the string that is its first argument. For example: 

$words[0] = "My"; 
Swords [1] = "short" ; 
$words[2] = "sentence."; 
$sentence = implode(" ", Swords); 
print("$sentence<BR>") ; 

produces the browser output: 

My short sentence, 
expl ode ( ) reverses the process, creating an array from a string: 

Swords = explode(" ", "My short sentence."); 



Integer overflow 

One clever automatic type conversion built into PHP relatively recently is that when integer values 
overflow (that is, they are assigned a value larger than they can hold), they become floats. This makes 
some sense, because floats can accommodate larger magnitudes than integers can. For example: 

$toobi g = 111 ; 

for ($count = 0; $count < 5; $count++) 
{ 

$too_big = 1000 * $too_big; 

print ("Is $too_big still an i nteger?<BR>" ) ; 

} 

produces the following browser output: 

Is 111000 still an integer? 

Is 111000000 still an integer? 

Is 111000000000 still an integer? 

Is 1.11E+14 still an integer? 

Is 1.11E+17 still an integer? 

The shift you see in this example from literal integers to scientific notation reflects a change of 
$too_bi g's type from integer to float. Of course, this may lose some information, because the preci- 
sion of floats is limited, but it is in keeping with the PHP philosophy of doing the best it can in pref- 
erence to causing an error. 
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Finding the largest integer 



If you need to know the largest integer your PHP will support and, for some reason, you believe that 
it is not the usual 2 31 - 1, here's a handy function (which uses concepts not yet covered): 

f uncti on maxi nt ( ) 

{ /* qui ck-and-di rty function for PHP int size - 
assumes largest integer is of form 2 A n - 1 */ 
$to_test = 2; 
while(l) 

t 

$last = $to_test; 
$to_test = 2 * $to_test; 

if (($to_test < $last) || ( ! i s_i nt ( $to_test ) ) ) 
return( $1 ast + ( $1 ast - 1 ) ) ; 



/* sample use */ 

$maxi nt = maxi nt ( ) ; 

pri nt( "Maxi nt is $maxi nt<BR>" ) ; 



Summary 

PHP6 has eight types: integer, float, boolean, NULL, string, array, object, and resource. Five of these 
are simple types: Integers are whole numbers, floats are floating-point numbers, booleans are true- 
or-false values, NULL has just one value (N U L L), and strings are sequences of characters. Arrays are 
a compound type that holds other PHP values, indexed either by integers or by strings. Objects are 
instances of programmer-defined classes, which can contain both member variables and member 
functions, and which can inherit functions and data type from other classes. Finally, resources are 
special references to memory allocated from external programs, which memory PHP frees automati- 
cally when they are no longer needed. 

Only values are typed in PHP — variables have no inherent type other than the value of their most 
recent assignment. PHP automatically converts value types as demanded by the context in which the 
value is used. The programmer can also explicitly control types by means of both conversion func- 
tions and type casts. 
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In Chapter 5 we presented the basic features for user-defined functions 
in PHP. In this chapter, we move on to some exotic properties of func- 
tions, including ways to use variable numbers of arguments, ways to 
have functions actually modify the variables they are passed, and (cooler 
still) using functions as data. 



Variable Numbers of Arguments 

It's often useful to have the number of actual arguments that are passed to a 
function depend on the situation in which it is called. There are three pos- 
sible ways to handle this in PHP: 

■ Define the function with default arguments — any that are miss- 
ing in the function call will have the default value, and no warn- 
ing will be printed. 

■ Use an array argument to hold the values — it is the responsibility 
of the calling code to package up the array, and the function body 
must appropriately take it apart. 

■ Use the variable-argument functions (f u n c_n u m_a r g s ( ) , 

f unc_get_a rg ( ) , and f unc_get_a rgs ( )). 



IN THIS CHAPTER 



Variable numbers of arguments 

Call-by-value 

Call-by-reference 



Variable function names 



Example: A cipher code 



The following sections address each of these possibilities. 
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To define a function with default arguments, simply turn the formal parameter name into an assign- 
ment expression. If the actual call has fewer parameters than the definition has formal parameters, 
PHP will match actual with formal until the actual parameters are exhausted and then will use the 
default assignments to fill in the rest. 

For example, the following function has all its variables defined with defaults: 

function tour_gui de ( $ci ty = "Gotham City", 

$desc = "vast metropolis", 

$how_many = "dozens", 

$of_what = "costumed villains") 

{ 

print("$city is a $desc filled with 
$how_many of $of_what . <BR>" ) ; 

} 

tour_guide( ) ; 

t o u r_g u i d e ( " C h i c a g o " ) ; 

tour_gui de ( " Chi cago" , "wonderful city"); 
tour_gui de ( " Chi cago" , "wonderful city", 

" teemi ng millions"); 
tour_gui de (" Chi cago" , "wonderful city", 

" teemi ng millions", 

"gruff people with hearts of 
gold and hard-luck stories to tell"); 

The browser output is something like this, with the intrasentence line breaks, of course, determined 
by your browser: 

Gotham City is a great metropolis filled with dozens of costumed 
villains. 

Chicago is a great metropolis filled with dozens of costumed 
villains. 

Chicago is a wonderful city filled with dozens of costumed 
villains. 

Chicago is a wonderful city filled with teeming millions of 
costumed villains. 

Chicago is a wonderful city filled with teeming millions of 
gruff people with hearts of gold and hard-luck stories to tell. 

The main limitation of default arguments is that the matching of actual to formal parameters is 
determined by the ordering of both — it's first-come, first-served. This means that there is abso- 
lutely no way to use the default-argument mechanism to tell someone about hard-luck stories in 
Gotham City. 
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Arrays as multiple-argument substitutes 

If you are dissatisfied with the flexibility of multiple arguments, you can bypass the whole argument- 
counting issue by using an array as your communication channel. 

The following example uses this strategy and, in addition, uses a few tricks like the ternary operator 
(introduced in Chapter 5) and the associative array (covered in Chapters 8 and 21): 

function tour_brochure ( $ i nf o_a r ray ) 

{ 

$city = 

IsSet($info_array[ 'city ' ] ) ? 
$ i nf o_a rray [ ' ci ty ' ] : "Gotham City"; 
$desc = 

I sSet ( $ i nf o_a may [ ' desc ' ] ) ? 
$i nfo_array[ ' desc ' ] : "great metropolis"; 
$how_many = 
I sSet ( $ i nf o_a r ray [ ' how_many ' ] ) ? 
$i nfo_array[ ' how_many ' ] : "dozens"; 
$of_what = 
I sSet ( $ i nf o_a r ray [ ' of_wha t ' ] ) ? 
$i nfo_array[ ' of_what ' ] : "costumed villains"; 

print("$city is a $desc filled with 
$how_many of $of_what . <BR>" ) ; 

) 

This function checks the single incoming array argument for four different values associated with 
particular strings. Using the ternary conditional operator ?, local variables are assigned to either the 
incoming value (if it has been stored in the array) or to our comic book defaults. Now, let's try call- 
ing this function with a couple of different arrays: 

tour_brochure(array( ) ) ; // empty array 
$tour_info = 
array('city' => 'Cozumel', 

'desc' => 'destination getaway', 

'of_what' => 'sandy beaches'); 
tour_brochure ( $tour_i nf o ) ; 

In this example, we call tour_brochure first with an empty array (corresponding to no arguments) 
and then with an array that has three of the four possible associative values stored in it. The browser 
output we get is: 

Gotham City is a great metropolis filled with dozens of costumed 
villains. 

Cozumel is a destination getaway filled with dozens of sandy 
beaches . 

In both cases, the dozens amount is defaulted, because neither array had anything stored under the 
how_many association. 
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Multiple arguments in PHP4 and above 

Beginning with version 4, PHP offers some functions that can be used inside function bodies to 
recover the number and values of arguments. They are: 

■ func_num_args(): Takes no arguments and returns the number of arguments that passed 
to the function it is called from. 

■ f unc_get_a rg ( ) : Takes an integer argument n and returns the nth argument to the func- 
tion it is called from. Arguments are numbered starting from zero. 

■ f unc_get_a rgs ( ) : Takes no arguments and returns an array containing all the argu- 
ments in the function it is called from, with array indices starting from zero. 

All three of these functions will produce a warning if called outside a function body, and f unc_ 
get_a rg ( ) will give a warning if it is called with an index higher than the index of the final argu- 
ment that was passed. 

If your function is going to handle the decoding of arguments using these functions, you can take 
advantage of the fact that PHP doesn't complain about function calls that have more arguments than 
formal parameters in the definition. Simply define your function to take no arguments, and then use 
the functions to catch any that are actually passed. 

As an example, consider the following two functions, both of which return an array of the argu- 
ments they are given: 

function args_as_array„l () 
{ 

$arg_count = f unc_num_a rgs ( ) ; 
$counter = 0; 
$local_array = arrayO; 
while ($counter < $arg_count) 
( 

$1 ocal_array[$counter] = 
f unc_get_a rg ( $counter) ; 
$counter = Icounter + 1; 

1 

return($local_array) ; 

} 

function args_as_array__2 () 
{ 

return ( f unc_get_a rgs ( ) ) ; 

} 

The first cumbersome function uses f un c_get_a rg ( ) to retrieve the individual arguments and 
bounds the loop using the result of f u n c_n u m_a r g s ( ) , so that no attempt is made to retrieve more 
arguments than were actually passed. Each argument is individually stored in an array, which is 
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then returned. Packaging up the arguments like this is already done for free byfunc_get_args( ), 
so the second version of the function is extremely short. 

As another example, let's rewrite our earlier tou r_g u i d e ( ) function to use the multiple-argument 
functions instead of default arguments: 

function toun_guide_2( ) 

( 

$num_args = f unc_num_args ( ) ; 
$city = $num_args > 0 ? 

f unc_get_a rg ( 0 ) : "Gotham City"; 
$desc = $num_args > 1 ? 

f unc_get_a rg ( 1 ) : "great metropolis"; 
$how_many = $num_args > 2 ? 

f unc_get_a rg ( 2 ) : "dozens"; 
$of_what = $num_args > 3 ? 

f unc_get_a rg ( 3 ) : "costumed villains"; 



print("$city is a $desc filled with 
$how_many of $of_what . <BR> " ) ; 

1 

tour„gui de_2( ) ; 



This has exactly the same behavior as the default-argument version and is subject to the same limita- 
tion. The arguments are passed in by position, so there is no way to replace "costumed villains" 
with something else while leaving "Gotham City" as the default. 

Unfortunately, no better solution presents itself in PHP6; the array solution is, if somewhat more 
code-intensive, still the most flexible. 



Call-by-value 

The default behavior for user-defined functions in PHP is call-by-value. This means that when you 
pass variables to a function call, PHP makes copies of the variable values to pass on to the function. 
So, whatever the function does, it is not able to change the actual variables that appear in the func- 
tion call. This behavior can be good or bad. It's a nice reassurance if you only want to use a function 
for its returned value, but it can also be a source of confusion and frustration if changing the passed 
variable is actually your goal. 

9 A " - 9 . 'Sf One of the most important differences introduced with the previous version of PHP, 
" w - - ^ version 5, and its predecessors, is that object instances are always effectively passed by 

reference, even if a value of another type would be passed by value. This is the result of the fact that 
object variables store object handles rather than the objects themselves — the handles actually are 
copied in a pass-by-value situation, but the underlying objects are not. (We dealt with this issue in 
more detail in Chapter 20.) 
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Let's demonstrate call-by-value with a fragile and extremely inefficient implementation of 
subtraction: 

function my_subtract ($numl, $num2) 
{ 

if ($numl < $num2) 

di e ( " Negat i ve numbers are imaginary"); 
$return_resul t = 0; 
while($numl > $num2) 



return($return_result) ; 

} 

$first_op = 493; 
$second_op = 355; 

$resultl = my_subt ract ( $f i rst_op , $second_op); 
print("resultl is $resultl<BR>"); 
$result2 = my_subtract( $f i rst_op , $second_op); 
pri nt( "resul t2 is Iresul t2<BR>" ) ; 

Reassuringly, we find that our result is the same both times we perform the same subtraction: 

resultl is 138 
result2 is 138 

This is true even though my„subtract changes the value of its formal parameter $numl — that 
variable only holds a copy of the value that was in the actual parameter $f i rst_op, and so 
$f i rst_op cannot be affected. 



PHP offers two different ways to have functions actually modify their arguments: in the function 
definition and in the function call. 

If you want to define a function to operate directly on a passed variable, simply put an ampersand in 
front of the formal parameter in the definition, like this: 

function my_subtract_ref (&$numl, &$num2) 
{ 

if ($numl < $num2) 

di e (" Negat i ve numbers are imaginary"); 
$return_resul t = 0; 
while($numl > $num2) 



$numl = $numl - 1; 

$return_resul t = $return_resul t + 1; 



Call-by-reference 



$numl = $numl 



1 ; 
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$return_resul t = $return_resul t + 1; 

} 

return ($ ret urn_resul t) ; 

} 

$fi rst_op = 493; 
$second_op = 355; 

$resultl = my_subtract_ref ( $f i rst_op , $second_op) ; 
print(" resultl is $resultl<BR>"); 
$result2 = my_subtract_ref ( $f i rst_op , $second_op) ; 
print("result2 is $resul t2<BR>" ) ; 

Now, if we perform exactly the same subtraction calls as we did the first time, we get the output: 

resultl is 138 
resultl is 0 

This is because the formal parameter $ nil ml refers to the same thing as the actual parameter 
$f i rst_op — changing one means changing the other. 

You can also force a function to take arguments by reference by prepending the actual parameters with 
ampersands (although this is a deprecated capability and may disappear in future PHP versions — in 
fact, it causes an E_STRICT level error in PHP6). That is, we can use our original call-by-value function 
and get the by-reference behavior, like this: 

$fi rst_op = 493; 
$second_op = 355; 

$resultl = my_subtract ( &$f i rst_op , &$second_op ) ; 
pri nt( " resul tl is $ res ul tl<BR> " ) ; 

$result2 = my_subtract ( &$f i rs t_op , &$second_op ) ; 
print("result2 is $ res ul t2<BR> " ) ; 

producing, once again: 

resultl is 138 
resultl is 0 

As of PHP4, variable references can be used outside of function calls as well. In general, assigning a 
variable reference (&$varname) to a variable will make the two variables aliases of each other rather 
than distinct variables with the same value. For example: 

$name_l = "Manfred von Richtofen"; 
$name_2 = "Percy Blakeney"; 
$alias_l = $name_l; // vars have same value 
$alias_2 = &$name_2; // vars are the same 

$alias_l = "The Red Baron"; // doesn't change real name 
$alias_2 = "The Scarlet Pimpernel"; // anonymous forever 

pri nt( "$al i as_l is $name_KBR> " ) ; 
pri nt( "$al i as_2 is $name_2<BR> " ) ; 
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gives the browser output: 



The Red Baron is Manfred von Richtofen 

The Scarlet Pimpernel is The Scarlet Pimpernel 




As we noted in the "Call-by-value" section, in PHP6 it is not necessary to explicitly make 
references to object instances. Objects are always effectively passed by reference. 



Variable function names 



One of the neater tricks you can do in PHP is to use variables in place of the names of user-defined 
functions. That is, rather than typing a literal function name into your code, you type a dollar-sign 
variable — the function that is actually called at runtime will depend on the string that that variable 
has been assigned to. In some sense, this allows us to use functions as data. This kind of trick will 
be familiar to advanced C programmers and to even beginning users of any kind of Lisp language 
(for example, Scheme or Common Lisp). 

For example, the following two function calls are exactly equivalent: 

function customi zed_greeti ng () 
{ 

print("You are being greeted in a customized way!<BR>"); 

1 

customi zed_greeti ng ( ) ; 

$my_greeting = ' customi zed_greeti ng ' ; 

$my_greeti ng( ) ; 

and produce the same output: 

You are being greeted in a customized way! 
You are being greeted in a customized way! 

Because function names are just strings, they can also be used as arguments to functions or be 
returned as a function's result. 



Just for fun, let's see what kinds of trouble we can get into by using some of the more advanced fea- 
tures of functions, including using function names as function arguments. 

Listing 26-1 shows an extended example of functions that implement a substitution cipher — a 
rudimentary kind of cryptography that scrambles messages by substituting one letter of the alphabet 
for another. 



An extended example 
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LISTING 26-1 



A substitution cipher 

/* Part 1 - cipher algorithm and utility functions */ 
function add_l ($num) 

{ 

return( ( $num + 1 ) % 26) ; 

) 

function sub_l ($num) 
{ 

return( ($num + 25) % 26) ; 

} 

function swap_2 ($num) 

{ 

if ($num % 2 == 0) 

return ( $num + 1 ) ; 
else 

return ( $num - 1 ) ; 

} 

function swap_26 ($num) 
{ 

return(25 - $num) ; 

} 

function 1 ower_l etter ( $cha r_st ri ng ) 
{ 

return ( ( ord ( $char_stri ng ) >= ord('a')) && 
( ord ( $char_stri ng ) <= ord('z'))); 

} 

function upper_l etter ( $cha r_st ri ng ) 
{ 

return ( ( ord ( $char_stri ng ) >= ord('A')) && 
( ord ( $char_stri ng ) <= ord('Z'))); 

) 

/* Part 2 - the 1 etter_ci pher function */ 
function 1 etter_ci pher ( $char_stri ng , $code_func) 
{ 

if (!( upper_l etter ( $cha r_stri ng ) | 
1 ower_l etter ( $cha r„stri ng ) ) ) 

return ( $cha r_s t r i ng ) ; 
if ( upper_l etter ( $cha r_stri ng ) ) 

$base_num = ord( ' A' ) ; 
else 



451 



Part III 



More PHP 



$base_num = ord ( ' a ' ) ; 
$char_num = ord( $char_s 
$base_n 

return ( chr ( $base_num + 
( $code_f unc 



t r i n g ) 
urn ; 



($char_num) 



% 26))); 



! 



/* Part 3 - the main stri ng_ci pher function */ 
function stri ng_ci pher( $message , $ci pher_f unc ) 
{ 

$coded_message = " " ; 

$message_l ength = stri en( $message) ; 

for (Sindex = 0; 

$index < $message_l ength ; 
$i ndex++) 
$coded_message .= 

1 etter_ci pher($ me ssage[$ index], $ci pher_f unc ) ; 
return ( $coded_message ) ; 



Listing 26-1 is in three parts. In the first part, we define a few functions that do simple math on the 
numbers from 0 through 25, which will represent the letters A-Z in our cipher codes. Function add_l 
simply adds 1 to the number it is given, modulo 26 (which just means that numbers that are 26 and 
larger "wrap around" to start from zero again). 0 + 1 is 1, 1 + 1 is 2, . . . and 25 + 1 is 0. Sub_l shifts 
numbers in the other direction, by adding 25 (which in this modular arithmetic is equivalent to sub- 
tracting 1). 25 + 25 is 24, 24 + 25 is 23, . . . and 0 + 25 is 25. Swap_2 trades the places of pairs of num- 
bers (0 to 1, 1 to 0, 2 to 3, 3 to 2, . . .). Swap_26 trades high numbers for low numbers (25 to 0, 0 to 25, 
24 to 1, 1 to 24, . . .). Each one of these functions will be the basis of a simple cipher code. Finally, we 
have a couple of utility functions that test whether a character is an uppercase or lowercase letter. 

Part 2 is a single function called letter_cipher(), whose job is to take a math function, like the 
ones in Part 1, and apply it to encode a single letter. First, it tests whether the string it is handed 
(which should be a single character) is an alphabetic letter; if not, it returns it as is. If the character is a 
letter, it is transformed into a number using ord ( ) , and the appropriate letter (a or A) is subtracted to 
bring the number into the 0-25 range. When it is in that range, we apply the cipher function whose 
name was passed in as a string, and then we convert the number back into a letter and return it. 

Finally, Part 3 is the single s t r i n g_c i p h e r ( ) function, which takes a string message and a cipher 
function and returns a new string that is the message encoded via the function. It does this by 
building a new string, letter by letter, from the message string, where each new letter is the result of 
applying $ c i p h e r_f u n c to the numerical representation of the old letter. 

Now let's write some code to try out s t r i n g_c i p h e r ( ) : 

$original = "My secret message is ABCDEFG"; 
print( "Original message is: $ori gi nal <BR>" ) ; 
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$coding_array = a rray ( ' add_l ' , 

' sub_l ' , 
' swap_2 ' , 
' swap_26 ' ) ; 

for ($count = 0; 

$count < si zeof ( $codi ng_a rray ) ; 
$count++) 

{ 

$code = $codi ng_array [$count] ; 
$coded_message = 

st ri ng_ci pher($original , $code) ; 
print("$code encoding is: $coded_message<BR>" ) ; 

} 

This testing code takes our four predefined letter-encoding functions, stashes them in an array, and 
then loops through the array, encoding the $ o r i g i n a 1 message and printing out the encoded version. 
The browser output looks like the following: 

Original message is: My secret message is ABCDEFG 
add_l encoding is: Nz tfdsfu nfttbhf jt BCDEFGH 
sub_l encoding is: Lx rdbqds Idrrzfd hr ZABCDEF 
swap_2 encoding is: Nz tfdqfs nfttbhf jt BADCFEH 
swap„26 encoding is: Nb hvxivg nvhhztv rh ZYXWVUT 

We can take this function-as-data approach one step further and write a function that applies more 
than one cipher to a message in sequence. This function also uses the variable-argument capability 
we discussed earlier in the chapter. 

function cha i ned„code (Smessage) 
{ 

/* takes a message, then an arbitrary number of 

cipher-code function names. Returns 

result of applying each code to the previous 

result. */ 
large = f unc_num_a rgs ( ) ; 
Icoded = Smessage; 

for ($count = 1; $count < $argc; $count++) 
t 

$f uncti on_name = f unc_get_a rg ( Scount ) ; 
$coded = 

stri ng_ci pher($coded, 

$f uncti on_name ) ; 

1 

return ( Scoded ) ; 

1 

The first argument to chai ned_code ( ) should be a message string, followed by any number of 
names corresponding to cipher functions. The coded message is the result of applying the first coding 
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function to the message, then applying the second coding function to the result, and so on. We can 
test it with various combinations of our predefined letter-coding functions, as follows: 

$ t r i c ky = 



Eeasy = 



original 






add_l' , 


' swap_ 


26' 


add_l' , 


' swap_ 


2' ) 


coded ve 


r s i o n 


i s 


original 






add_l' , 


' swap_ 


26' 


swap_2 ' , 


' s ub_ 


1' , 


add_l' , 


' swap_ 


2' , 


swap_26 ' 


, 'sub 


_r 


ded vers 


ion is 


$e 



with these results: 

Tricky encoded version is Ma guwjuh muggysu qg YZWXUVS 
Easy encoded version is My secret message is ABCDEFG 

As you can see, the tricky encoding of our message is a combination of our previous codes that 
doesn't correspond exactly to any of those single coding functions. And the "easy" coding is an 
even more complicated combination of those functions that produces . . . our original message 
unchanged! (No, it's not that our cipher code doesn't work — we'll leave it to you to figure out why 
that particular sequence of coding functions brings us around to our starting message again.) 

The moral of our little cryptographic scripting story is that, although the cipher code was mildly 
complicated, it was made considerably simpler by PHP's support for using function names as func- 
tion arguments. 



Summary 

The default behavior for user-defined functions is call-by-value, meaning that functions work on cop- 
ies of their arguments and so cannot modify the original variables in the function call. You can force 
call-by-reference behavior by preceding parameters with &, on either the definition side or the calling 
side. PHP offers more than one way to let functions take a variable number of arguments. Finally, 
the functions to be called can be determined at runtime, by substituting a string variable for the lit- 
eral name of the user-defined function — this allows functions to be treated as data and passed back 
and forth between other functions. 
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In Chapter 9, we covered the most basic aspects of mathematics in 
PHP: the numerical types, the basic arithmetic operators, a small set of 
arithmetic functions, and (because it is so widely used in web script- 
ing) pseudo-random number generation. In this chapter, we round out this 
coverage by enumerating the built-in mathematical constants; exploring 
trigonometric, logarithmic, and base conversion functions, and explaining 
PHP's be module for arbitrary-precision arithmetic. 



Mathematical Constants 

When we wrote the first edition of this book (around the release of PHP 
version 4.0), there was only one documented math constant: M_PI (the 
value of pi as a double). However, many new constants were introduced 
with PHP v4.0.2. Most of these new constants had to do with pi (or mul- 
tiples thereof), e (or multiples thereof), or square roots, with a few odd- 
balls thrown in. The list has since shrunk back down to a slightly smaller 
number of predefined mathematical constants, for a variety of reasons. 
Those that remain are listed in Table 27-1. The general naming scheme 
is M„<constant-name>. In cases where the constant is a ratio (x/y), the 
name is M_X_Y , and in cases where there is an operation on a number, the 
name is M_0PERNUM (for example, M_SQRT2). 



IN THIS CHAPTER 



Mathematical constants 
Tests on numbers 



Base conversion 



Exponents and logarithms 
Trigonometry 

Arbitrary precision arithmetic 
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TABLE 27-1 



Mathematical Constants 


Constant 


Description 


M_PI Pi 


m n T o 


pi/2 


y nT A 


pi/4 


N_1_H 1 


I /pi 


M 9 D T 


z/pi 


M_2_SQRTPI 


2/sqrt(pi) 


M_E 


the constant e 


M_SQRT2 


sqrt(2) 


M_SQRT1_2 


1/sqrt(2) 


M_L0G2E 


log 2 (e) 


M_L0G10E 


log 10 (e) 


M„LN2 


log e (2) 


M_LN10 


log e (10) 



Tests on Numbers 

PHP offers a handful of functions for doing tests on numbers. Despite PHP's type looseness, it's a good 
idea to employ some of these tests in your code to help anticipate what sorts of results you will get, 
and how best to handle them. 

The first and simplest test is i s_n ume r i c ( ) . Like most of these tests, i s_n ume r i c returns a 
Boolean result, True if the supplied parameter is any type of number (signed or unsigned, integer or 
float) or a mathematical expression that returns a valid number: 

i s_numeri c ( 4 ) // True 
is numeric(4-4) // True 
i s_numeri c(4*4) // True 

Some caution is warranted, because even if you intend to test a string, a string that could be seen as 
an algebraic expression by PHP might also return a True value: 

i s_numeri c ( bel 1 s /4 ) // True 
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Finally, remember not to inadvertently put quotation marks around a mathematical expression, as 
the result will be forced to F a 1 s e by the string indicators, even though quoting a simple number or 
double will not cause this behavior: 

i s_numeri c( ' M_PI * 3') // False 
i s_numeri c( ' 123456 ' ) // True 

In cases like the preceding code snippet, it may be desirable to test with a higher degree of specificity, 
that is to say, for one of PHP's numeric subtypes, using is_int( ) or is_float( ). Neither of these 
tests is substantively different from i s_n ume r i c ( ) in their mode of operation. They simply test for a 
particular numeric type. Here are more usage examples and what you might expect from each: 

is_int(4) // True 

i s_i nt ( 4 . 2 ) // False, it's a Tloat or double 

i s_i nt ( ' 4 ' ) // False, this test is stricter than is numeric 

is_int(4 * 2) // True, this expression yields an integer 

You might also occasionally see the test i s_l ong ( ) . This test simply maps to the i s_i nt ( ) func- 
tion. The other numeric type in PHP can be tested for using i s_f 1 oa t ( ) , which is aliased by 
i s__doubl e ( ) . Again, usage is not exactly tricky or even complex. 

is_float(4) // False, but you knew that already 
i s_f 1 oat (4 . 212 ) // True, but you knew that as well 
is_float(4 / 3) // True 

i s_f 1 oat ( M_P I ) // True, maybe you knew that, maybe you didn't 

Two more tests are slightly more obscure: i s_f i n 1 1 e ( ) and i s_i n f i n i t e ( ) test for exactly what 
their names suggest, although strictly speaking, their range is governed not by actual infinity (how 
would you test that?) but by the boundaries of the float value that your system allows. 

Finally, we have i s_n a n ( ) , which we covered in Chapter 9. You might be tempted to use i s_n a n ( ) 
to test for any non-numeric value. You'll be unpleasantly surprised if you rely on this functionality. 
The more appropriate use of this function is to test for an unreasonable or improbable mathematical 
expression such as a c o s ( 2 ) . 



Base Conversion 

The default base in PHP for reading in or printing out numbers is 10. In addition, you can instruct 
PHP to read octal numbers in base 8 (by starting the number with a leading 0) or hexadecimal num- 
bers in base 16 (by starting the number with a Ox). 

r* A rc'~ '■ i: ' For more on read formats of numbers, including octal and hexadecimal notation, see 

Chapter 54. 
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A Glimpse behind the Curtain 

How are built-in PHP functions really implemented? This is likely to be of interest only to C programmers 
and/or those who care about the inner workings of PHP, but we thought that it might be revealing to see 
why so many PHP functions work just like their C counterparts. 

What follows is the actual implementation for the PHP function ceil, which is intended to convert a double 
to the smallest integer that is greater than or equal to it. 

PHP_FUNCTION(ceil ) 
t 

zval **value; 

if (ARG_COUNT(ht) !=1 | ] getParametersEx( 1 ,&val ue)==FAI LURE) { 
WRONG_PARAM_COUNT ; 

} 

convert_scal ar„to_number_ex( val ue ) ; 

if ((*va1ue)->type == IS_D0UBLE) { 

RETURN_LONG((long)cei 1 ( ( *val ue ) ->val ue . dval ) ) ; 
) else if ((*value)->type == IS_L0NG) { 
RETURN_LONG( ( *val ue ) ->val ue . 1 val ) ; 

} 

RETURN_FALSE ; 

1 



Although the capitalized portions (including the PHP_FUNCTION declaration) are macros specific to the PHP 
framework, much of the body of this code is straight C. The code might look dense and confusing at first, 
but most of the action has to do with PHP's special treatment of types. Here is roughly what is happening, in 
order: 

1. The arguments that ceil ( ) was called with are retrieved and counted — if the count is anything 
other than 1, the function call returns with an error. 

2. The single argument is converted to a number if it is a scalar type other than a number — this 
handles the possibility of string arguments, as in ceil ("5.4"). 

3. Now the numerical argument is tested to see whether it is a PHP long (aka integer) or a PHP dou- 
ble. If it turns out to be a long, the value as a long is returned. 

4. The interesting case is if the value is a PHP double. If so, the C double value is extracted, it is run 
through the C function ceil, the result is converted to a C long, then that value is wrapped up and 
returned as a PHP long. 

In other words, the PHP implementation of cei 1 is simply the C function ceil, wrapped up in a lot of type 
conversion and argument checking. This is the case with many of PHP's functions that have exact analogues 
in C. 
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Once numbers are read in, of course, they are represented in binary format in memory, and all the 
basic arithmetic and mathematical calculations are carried out internally in base 2. PHP also has a 
number of functions for translating between different bases, which are summarized in Table 27-2. 



TABLE 27-2 



Base Conversion Functions 


Function 


Behavior 


BinDec( ) 


Takes a single string argument representing a binary (base 2) integer and returns a 
string representation of that number in base 10. 


DecBin( ) 


Like Bi nDec ( ), but converts from base 10 to base 2. 


OctDec( ) 


Like Bi nDec ( ), but converts from base 8 to base 10. 


DecOct( ) 


Like Bi nDec ( ), but converts from base 10 to base 8. 


HexDec( ) 


Like Bi nDec ( ), but converts from base 16 to base 10. 


DecHex( ) 


Like Bi nDec ( ), but converts from base 10 to base 16. 


baseconvert( ) 


Takes a string argument (the integer to be converted) and two integer arguments 
(the original base, and the desired base). Returns a string representing the converted 
number — digits higher than 9 (from 10 to 35) are represented by the letters a-z. 
Both the original and desired bases must be in the range 2-36. 



All the base-conversion functions are special-purpose, converting from one particular base to 
another, except for base__convert ( ) , which accepts an arbitrary start base and destination base. 
Here's an example ofbase__convert() in action: 

function di spl ay_bases ( $start_stri ng , $start_base) 
{ 

for ($new_base = 2; $new_base <= 36; $new_base++) 
{ 

$converted = 

base_convert ( $sta rt_st ri ng , $start_base, $new_base); 
pri nt ( " $start_st r i ng in base $start_base 

is Sconverted in base $new_base<BR>" ) ; 




di spl ay_bases ( "1 j j " , 20); 
This code yields the browser output: 

ljj in base 20 is 1100011111 in base 2 
ljj in base 20 is 1002121 in base 3 
ljj in base 20 is 30133 in base 4 
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Ijj 
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base 
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11144 in base 
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i n 


base 


20 
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3411 


in base 6 
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2221 
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base 


20 
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1437 
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base 
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i s 


1077 
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20 
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799 
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667 
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i s 


16o 


in base 25 


Ijj 


i n 


base 


20 
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po i 


n base 31 


Ijj 


i n 


base 


20 


i s 


ov i 


n base 32 


Ijj 


i n 


base 


20 


i s 


o7 i 


n base 33 


Ijj 


i n 


base 


20 


i s 


nh i 


n base 34 


Ijj 


i n 


base 


20 


i s 


mt i 


n base 35 


Ijj 


i n 


base 


20 


i s 


m7 in base 36 



Notice that although all the base-conversion functions take string arguments and return string val- 
ues, you can use decimal numerical arguments and rely on PHP's type conversion (but see the cau- 
tionary note that follows). In other words, both DecBi n ( " 1234" ) and DecBin(1234) will yield the 
same result. 



c , ' ' "^T^'.jvj"''" Don't confuse the read formats of numbers with their representations as strings for the 
tS^m^mA^m^K purposes of base conversion. For example, although 10 in base 16 is the number 16 in 

base 10, the expression HexDec(OxlO) evaluates to the string "22". Why? There are really three con- 
versions happening: when 0x10 is read (converts from hex to internal binary), when the argument is 
auto-converted (from internal binary number to the decimal string " 16 "), and in the operation of the 
function (from assumed base 16 to decimal " 22 "). If you want just one conversion, the desired expres- 
sion is HexDec( "10" ). 



CAUTION 



decimal 2.5. 



The base conversion functions expect their string arguments to be integers, not floating- 
point numbers. That means you can't use these functions to convert a binary 10.1 to a 
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Exponents and Logarithms 

PHP includes the standard exponential and logarithmic functions, in both base 10 and base e variet- 
ies (shown in Table 27-3). 



TABLE 27-3 



Exponential Functions 


Function 


Behavior 




pow( ) 


Takes two numerical arguments and returns the first argument raised to th 
the second. The value of pow( $x , $y) is x^. 


e power of 


exp( ) 


Takes a single argument and raises e to that power. The value of exp ( $x 


) is e x . 


log() 


The "natural log" function. Takes a single argument and returns its base e 
ev = x, then the value of 1 og ( $x ) is y. 


logarithm. If 


loglOO 


Takes a single argument and returns its base-10 logarithm. If 10 y = x, then 

1 oglCK $x) is y. 


the value of 



Unlike with exp ( ) and the base e, there is no single-argument function to raise 10 to a given power, 
but in its place you can use the two-argument function pow( ) with 10 as the first argument. 

You can verify that exponential and power functions of the same base are inverses of each other, by 
testing an identity like this: 

$test_449 = 449.0; 

$test_449 = pow(10, exp ( 1 og ( 1 oglO ( $test_449 ) ) ) ) ; 
print("test_449 is $test_449<BR> " ) ; 

which gives the browser output: 
test_449 is 449 



Trigonometry 

Although explaining the math behind the PHP functions in this chapter is beyond the scope of this 
book, we've made an exception just this once. (See the sidebar "Trigonometry in One Paragraph." 
Anyone who doesn't already know trigonometry will, of course, find the sidebar completely impen- 
etrable, but we hope that those who know trig will at least be amused by how short it is.) 

PHP offers the standard set of basic trigonometric functions as well as the constant M_P I , an approx- 
imation of pi as a double that prints as 3. 1415926535898. This constant can be used anywhere you 
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would use the literal number itself, and it is also interchangeable with the p i ( ) function. (For other 
constants derived from pi, see the "Mathematical Constants" section at the beginning of this chap- 
ter.) Both of the following statements have the same result: 

$my_pi = M_PI ; 
$my„pi = pi ( ) ; 

The basic trig functions are summarized in Table 27-4. 



TABLE 27-4 



Trigonometric Functions 


Function 


Behavior 


pi() 


Takes no arguments and returns an approximation of pi (3.1415926535898). Can be 
used interchangeably with the constant M P I . 


SinO 


Takes a numerical argument in radians and returns the sine of the argument as a 
double. 


CosO 


Takes a numerical argument in radians and returns the cosine of the argument as 
a double. 


TanO 


Takes a numerical argument in radians and returns the tangent of the argument as 
a double. 


Asin( ) 


Takes a numerical argument and returns the arcsine of the argument in radians. 
Inputs must be between -1.0 and 1.0 [inputs outside that range will return a result of 
NAN (for "not a number")]. Results are in the range -pi / 2 to pi / 2. 


Acos ( ) 


Takes a numerical argument and returns the arccosine of the argument in radians. 
Inputs must be between -1.0 and 1.0 [inputs outside that range will return a result of 
NAN (for "not a number")]. Results are in the range 0 to pi . 


AtanC ) 


Takes a numerical argument and returns the arctangent of the argument in radians. 
Results are in the range - pi / 2 to pi / 2. 


Atan2( ) 


A variant of atan ( ) that takes two arguments. Atan ( $y , $x ) is identical to 
atan($y/$x) when $x is positive, but the quadrant of a tan2's result depends on 
the signs of both $y and $x. Range of the result is from -pi to pi . 



Rather than writing down a table of sample function results, let's resort to our usual trick of writing 
code that automatically displays examples as an HTML table. Listing 27-1 shows both a generalized 
function for displaying a set of one-argument functions applied to a set of numerical arguments and 
then the result of using this display function to make trigonometric example tables. The results are 
displayed in Figure 27-1. 
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Trigonometry in One Paragraph 

Imagine a circle with a radius of 1, centered at 0,0 in the coordinate plane. Start at the right-hand edge (at 
position (1,0)), and trace a certain distance along the circle counterclockwise. For example, a distance of 2 
pi would take you once around the circle and back to your starting point. Clockwise travel counts as a negative 
distance. For any such distance, the sine function tells you the y-value of the coordinate you arrive at, the cosine 
function tells you the x-value of that coordinate, and the tangent function is a ratio of the two, from which you 
can infer the slope of the line tangent to the circle at that point. The functions arccosine, arcsine, and arctangent 
are in some sense inverses of their corresponding functions — they map back from an x, y, or y/x ratio to the 
distance of a circular trip that would arrive at that x-coordinate, y-coordinate, or ratio thereof. Because adding 
a multiple of 2 pi to any distance brings you around to the same point again, these inverse functions might 
have an infinite number of answers per input, making them ill-defined — instead, they are restricted to a range 
corresponding to one particular trip around half of the circle and so have well-defined results. 



LISTING 27-1 



Displaying trigonometric function results 

<?php 

function di spl ay_f unc_resul ts ( $f unc_anray , $ i nput_a nray ) 

( 

/* print a function header * / 

print ("<TABLE B0RDER=1XTRXTH>INPUT\\FUNCTI0N</TH>" ) ; 
for($y = 0; 

$y < count ( $func_ar ray ) ; 

$y++) 

pri nt( "<TH>$f unc_array [$y]</TH>" ) ; 
print("</TRXTR>"); 
/* print the rest of the table */ 
for($x = 0; 

$x < count ($ i nput_a r ray ) ; 

$x++) 

{ 

/* print column entries for inputs */ 
print("<TH>". 

spri ntf ( "%. 4f " , $i nput_ar ray [ $x] ) 
. "</TH>" ) ; 
for($y = 0; 

$y < count ( $func_ar ray ) ; 
$y++) 

{ 

$func_name = $f unc„array [$y] ; 
$input = $i nput_array [$x] ; 
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print("<TD>") ; 

printf ("X4.4f " , $f unc_name( $i nput ) ) ; 
print("</TD>") ; 

1 

pn'nt("</TRXTR>" ) ; 

} 

print( "</TRX/TABLE>" ) ; 
) 

?> 

<HTML> 
<HEAD> 

<TITLE>Tri gonometri c Function Exampl es</TITLE> 

</HEAD> 

<B0DY> 

<?php 

/* using the function displayer */ 
pri nt( "<H3>Tri gonometri c function exampl es</H3>" ) ; 
di spl ay_f unc_resul ts ( a rray ( " si n " , "cos", "tan"), 
array ( -1.25 * pi ( ) , 
-1.0 * pi ( ) , 
-0.75 * pi ( ) , 
-0.5 * pi ( ) , 
-0.25 * pi ( ) , 
0, 

0.25 * pi(), 
0.5 * pi ( ) , 
0.75 * pi ( ) , 

pi ( ) , 

1.25 * pi())); 

?> 

</B0DY> 
</HTML> 



- j * The d i spl ay f unc resul ts ( ) function of Listing 27-1 uses several tricks we've seen 

J ' in previous chapters: using a string variable as the name of a function to call (covered 

near the end of Chapter 26) and using the string concatenation operator (. ) to pull together a print 
string in the middle of a print statement (covered in Chapter 7). 

Figure 27-1 shows the basic trigonometric functions over an input range of - 5 / 4 p i to 5 / 4 p i and 
the basic inverse trigonometric function over inputs from - 1 . 0 to 1 . 0. The very large tangent values 
are due to denominators that should theoretically be zero but instead differ slightly from zero due to 
rounding error. 
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FIGURE 27-1 



Trigonometric function examples 



Trigonomeliic Function Examples - Manilla (Build ID: 2002051006} 
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Arbitrary Precision (BC) 



The integer and double types are fine for most of the mathematical tasks that arise in web scripting, 
but each instance of these types is stored in a fixed amount of computer memory, and so the size 
and precision of the numbers these types can represent is inherently limited. Although the exact 
range of these types may depend on the architecture of your server machine, integers typically range 
from -2 31 - 1 to 2 31 - 1, and doubles can represent about 13 to 14 decimal digits of precision. For 
tasks that require greater range or precision, PHP offers the arbitrary -precision math functions (also 
known as BC functions, from the name of the Unix-based, arbitrary-precision calculating utility). 



CAUTION 



Especially if you compiled PHP yourself, the arbitrary-precision functions may not have 
been included in the compilation — you need to have included the flag enable 
b cma t h at configuration time. To check whether the functions are present, try evaluating b c a d d ( " 1 " 
" 1 " ) — if you get an unbound function error, you will have to reconfigure and recompile PHP. 



Instead of using the fixed-length numerical types, the BC functions have strings as arguments and 
return values. Because strings in PHP are limited only by available memory, numbers can be as 
long as you like. The underlying computations are performed in decimal and are done much as you 
would do them with pen and paper (if you were very fast and very patient). When operating with 
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integers, the BC functions are exact and use as many digits as needed; when operating with floating- 
point numbers, computations are done to as many decimal places as you specify. The BC functions 
are summarized in Table 27-5. 

Most of the functions take an optional scale factor (an integer) as a final argument, which determines 
how many decimal places will be in the result. If such an argument is not supplied, the scale is the 
default scale, which, in turn, can be set by calling b c s c a 1 e ( ) . The default for the default value (that 
is, if b c s c a 1 e ( ) has never been called) can also be set in the initialization file p h p . i n i . 



TABLE 27-5 



Arbitrary-Precision (BC) Math Functions 


Function 


Behavior 


bcadd( ) 


Takes two string arguments representing numbers, and an optional integer scale 
parameter. Returns the sum of the first two arguments as a string, with the number of 
decimal places in the result determined by the scale parameter. If no scale parameter is 
supplied, the default scale is used (which is settable bybcscaleO). 


bcsub( ) 


Similar to bcadd( ), except that it returns the subtraction of the second argument from 
the first. 


bcmul ( ) 


Similar to bcadd ( ) but returns the product of its arguments. 


bcdi v ( ) 


Similar to bcadd ( ) but returns the result of dividing the first argument by the second. 


bcmod ( ) 


Returns the modulus (remainder) of the first argument as divided by the second. 
Because the return type is "integral," no scale argument is taken. 


bcpow( ) 


Raises the first argument to the power of the second argument. The number of decimal 
places in the result is set by the scale factor if supplied. 


bcsqrt ( ) 


Returns the square root of its argument, with number of decimal places set by the 
optional scale factor. 


bcscal e( ) 


Sets the default scale factor for subsequent BC function calls. 



An arbitrary-precision example 

Here's an example of using the arbitrary-precision functions for exact integer arithmetic. The 
following code: 

for ($x = 1 ; $x < 25; $x++) I 

print("$x raised to the power of $x is " . bcpow($x, $x) . "<BR>"); 

} 
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will print like this: 



1 raised 


to 


the 


Dower 


of 1 


i s 


1 
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the 
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of 
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88817841970012523233890533447265625 



If we had used the regular PHP integer type for this computation, the integers would have overflowed 
well before the end, and the rest of the loop would have been calculated in approximate floating point. 



Let's see what it's like to take an existing piece of mathematical code and retrofit it to use the arbi- 
trary-precision functions. 

The following function approximates pi, using the series approximation: 



(As we'll see, this series does not converge fast enough for our purposes, but it has the virtue of 
being a simple formula.) 

function pi_approx( $ i terati ons , $pri nt_f requency ) 
{ 

$squared_approx = 12; 
$next_sign = -1; 
Sdenom = 2; 



Converting code to arbitrary-precision 



sqrt ( 12 



(12/2 2 ) + ( 12/3 2 ) 



( 12/4 2 ) + (12/5 2 ) 
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for (liter = 0; liter < Siterations; $iter++) 
{ 

$squared_approx += $next_sign * 12/ ( pow( $denom , 2 ) ) ; 
$denom++; 

$next_sign = - $next_sign; 

if (Idenom % $pri nt_f requercy == 0) 

{ 

$estimate = sqrt( $squared_approx) ; 

pri nt ( " $denom iterations: $estimate<BR>" ) ; 

} 

} 

} 

In addition to performing the calculation itself, this code periodically prints its current estimate 
of pi, so we can see how we are doing. We can call it as follows and then print PHP's value for 
comparison: 

pi_approx( 10000 , 1000); 

printC'PHP value: " . pi ( ) . "<BR>"); 

The result looks like: 



1000 


i terati 


ons : 
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1415936094742 


2000 


i terati 
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1415927597285 


4000 
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1415927132878 
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3 


1415926917946 


6000 


i terati 
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14159268012 
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141592673081 


8000 


i t e r a t i 


ons : 


3 


1415926685124 


9000 


i terati 


ons : 


3 


1415926653804 



10000 iterations: 3.1415926631401 
PHP value: 3.1415926535898 

Now, not only are we not that close, but we can't hope to be more accurate than PHP's value for pi, 
because that already uses all the precision available in the double type. 

To convert this to an arbitrary-precision version, we must replace all the math functions and opera- 
tors that need precision with their BC counterparts, like this: 

function pi_approx_bc ( $i terati ons , $ p r i nt_f requency , $scale) 
{ 

$squared_approx = "12"; 
$next„sign = -1; 
$denom = 2; 

for ($iter = 0; liter < Siterations; $iter++) 
I 

$squared_approx 
= bcadd( 
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SsquarecLapprox, 
bcmul ( $next_s i gn , 
bcdi v ( 12 , 

bcpow( $denom , 
2, 

$scal e) , 
$scal e ) , 
$scal e ) , 
$scal e ) ; 
$denom++; 

$next_sign = - $next_sign; 
if ($denom % $ p r i nt_f requency == 0) 
{ 

$estimate = bcsqrt ( $squa red_approx , $scal e ) ; 
pri nt ( " $denom iterations: $esti mate<BR>" ) ; 

) 

} 

} 

Notice that although the BC functions want string arguments, we can, as always, use regular num- 
bers in their places and rely on PHP to convert the arguments to strings for us. Also notice that we 
did not bother making the numerical computations that do not require great precision into BC com- 
putations (for instance, we still have $denom++ rather than bcadd ( $denom , 1 ) . Finally, we added a 
scale argument to the entire function, which turns the decimal precision of each BC function it calls. 

Unfortunately, both your authors and our browsers ran out of patience with this series before it 
even got to the level of precision of PHP's value. Here are some late results of calling pi_approx_ 
bc(1250000, 50000, 50): 

50000 iterations: 3.14159265397177274129723551068347726371297686926596 
100000 iterations: 3.14159265368528715924598769254390594927146205337113 
150000 iterations: 3.14159265363223483956231649503922204272933217538202 
[..] 

1150000 iterations: 3.14159265359051530310455255409602580003265549955003 
1200000 iterations: 3.14159265359045638461148087403458918944405547147211 
1250000 iterations: 3.14159265359040439393304018710072157703501022388304 

The correct digits in the preceding output are about one digit shy of the PHP value. This is the fault 
of the series we chose rather than the arbitrary-precision libraries — with a more sophisticated and 
speedier approximation series, you too can serve up millions of digits of pi to your eager audience. 

Somewhat more satisfyingly, evaluating: 

print("The square root of two is " . bcsqrt(2, 40)); 
gives us many more digits of precision than we could get using doubles: 

The square root of two is 1.4142135623730950488016887242096980785696 
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Summary 

Although the primary purpose of PHP is not to do mathematics, it has a pretty comprehensive set of 
mathematical functions covering basic arithmetic, pseudo-random number generation, base conversion, 
trigonometry, exponents and logarithms, and a built-in module for doing arbitrary-precision arithmetic. 

We covered the numerical types and the most basic functions in Chapter 9, and covered the remain- 
ing topics in this chapter. Table 27-6 is a tabular summary of the operators and functions discussed 
both in Chapter 9 and this chapter. 



TABLE 27-6 



Summary of PHP Math Operators and Functions 


Category 


Description 


Arithmetic 
operators 


Operators +, *, /, % perform basic arithmetic on integers and doubles. 


Incrementing 
operators 


The ++ and - - operators change the values of numerical variables, increasing them 
by one or decreasing them by one (respectively). The value of the postincrement 
form ( $va r++) is the same as the variable's value before the change; the value of the 
preincrement form (++$ v a r) is the variable's value after the change. 


Assignment 
operators 


Each arithmetic operator (like +) has a corresponding assignment operator (+=). The 
expression $ count += 5 is equivalent to $count = $count + 5. 


Comparison 
operators 


These operators (<,<= , >,>=,==, !=) compare two numbers and return either trueor 
f al se. The === operator is true if and only if its arguments are equal and of the same type. 


Basic math 
functions 


f 1 oor ( ), ceil ( ), and round ( ) convert doubles to integers, mi n ( ) and max( ) take 
the minimum and maximum of their numerical arguments, and abs ( ) is the absolute 
value function. 


Base 

conversion 
functions 


Special-purpose functions (OctDec( ), DecOct( ), BinDec( ), DecBin( ), HexDec( ) , 
DecHexC )) convert between particular pairs of bases, whereas base_convert ( ) 
translates between arbitrary bases. 


Exponential 
functions 


Functions having to do with raising numbers to powers or the inverse: 1 og ( ) (natural 
log), 1 oglO ( ) (base-10 log), exp ( ) (e raised to the power of the argument), and pow( ) 
(first argument to the power of the second). 


Trigonometric 
functions 


Functions having to do with angular measures: pi ( ) (and the equivalent constant 

M_P I ),sin(),cos(),tan(),acos(), as i n ( ), atanO, and atan2( ) (a two- 
argument version of atan ( )). 


Arbitrary- 
precision (BC) 
functions 


Functions that do arithmetic on arbitrary-length strings representing decimal integers 
and floating-point numbers: bdadd( ), bcsub( ), bcmul t( ), bed i v( ), bcmod( ), 
bepow ( ), besq rt ( ) . Most of these functions take an optional scale parameter 
specifying the number of decimal points of precision desired — the default for that 
parameter is settable using bes ca 1 e ( ) . 
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ecurity is not a joking matter," proclaim signs at airports every- 
where. The same sign should be posted near your PHP server. 
Anyone connecting a server to the Internet must take proper 
security measures or risk loss of data or even money to the keystrokes of 
malicious crackers. 



The mantra of the security-conscious site designer is: Don't trust the net- 
work. If you're worried about the security of your site, chant this mantra as 
you code your pages. Any information transmitted to your server via the 
network — be it a URL, data from an HTML form, or data on some other 
network port — should be treated as potentially hazardous. This chapter 
suggests several techniques for sanitizing incoming information. You should 
apply these techniques and spend some time trying to discover other 
potential hazards and ways to prevent them. 

The second rule of thumb for a secure site is: Minimize the damage. What if 
the program you just wrote, which you are sure is secure, is actually vul- 
nerable? Just to be on the safe side, limit the damage an intruder can cause 
after he or she has taken advantage of the vulnerability. 

When visitors come to your site, they trust that it contains valid informa- 
tion, that it is not harmful to them or to their computers, and that any 
information they provide to it is handled properly. Interacting with a site, 
whether an e-business, recreational, or informational site, involves certain 
security risks for a visitor. As a site designer, it is your responsibility to pro- 
tect visitors from these risks. Besides being sure their information is safe on 
your server, this means you should take measures to safeguard their infor- 
mation while it is in transit from their computers to your server. 



IN THIS CHAPTER 



Possible attacks 
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But all this should not scare you away from putting your e-business online. The first section of this 
chapter describes some possible attacks against your server and ways to avoid them. We then discuss 
cryptographic techniques for protecting your data. At the end of this chapter, we list some web sites 
that contain up-to-the-minute information on the latest cracker techniques. By watching these sites, 
you may learn of possible security vulnerabilities before an attacker does and, thereby, avoid disaster. 



Possible Attacks 

Connecting your server to the Internet is like setting up a storefront on a busy street. You're likely 
to have quite a few visitors, but if you're not careful, some less than desirable visitors may take 
advantage of you. 



Crackers, script-kiddies, and other fiends 

The term hacker is commonly used to describe individuals more correctly labeled crackers. Within the 
computer community, crackers are those who, through luck or skill, break into computer systems and 
cause damage. Hackers are those who can hack — read and write efficient (and often obscure) code in many 
languages. To a programmer, being labeled a hacker is an honor, whereas being labeled a cracker probably 
means he or she should start reading the Help Wanted section. 

As if the term cracker were not sufficiently derogatory, young crackers who use tools and scripts they find on the 
web are called script-kiddies. These budding lawbreakers often have little understanding of what they are actually 
doing. They are usually the culprits behind low-tech attacks such as site defacement. A fairly good indicator of 
the work of a script-kiddie is the excessive use of misspelling and capitalization, as in W3 R KOOL DOODz. 



Site defacement 

Often more embarrassing than harmful, site defacements are fairly common because the cracker has 
an opportunity to publicize his or her exploitation. Site defacements are sometimes left as calling 
cards by a cracker who entered a system by more complicated means. 

It is possible to deface a badly designed web site using only a web browser. Take, for instance, the 
following program: 

<?php if (IsSet($_POST['visitor'])) ( 

$visitor = $_P0ST[ ' vi si tor ' ] ; 

$fp = f open ( "database" , "a"); 

fwri te( $f p , "<li>$visitor\n"); 

fclose($fp); ) ?> 
<HTML> 

<HEADX/HEAD> 
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<BODY> 

<Hl>Visitors to this site:</Hl> 
<0L> 

<?php $fp = fopen( "database" , "r"); 

print(fread($fp, f i 1 es i ze ( " database" )) ) 

fclose($fp) ?> 
</0L> 
<HR> 

<FORMXINPUT TYPE="TEXT" NAME="vi si tor"> 



<INPUT TYPE="SUBN 
</F0RM> 
</B0DY> 
</HTML> 



IT" NAME="submit" VALUE="Sign in!"> 



This program implements a very rudimentary guest book. In reading this code, however, you should 
feel a bit uneasy. Don't trust the network. This program accepts form data that we expect to contain 
the visitor's name (in the variable $ v i s i t o r) and stores it in a text file for display to subsequent 
visitors. For the inputs we expect, there is no trouble. 

Now put on your script-kiddie hat for a moment and imagine what would happen if the input con- 
tained HTML tags. This simple program would blindly insert those tags into the pages it generates, 
and other visitors' browsers would interpret them as usual. One particularly malicious tag is the 
<SC RI PT> tag. A cracker wishing to deface this web page could duplicate the page's appearance on 
his or her own server (www . exampl e . com) and then sign into the guestbook with the name: 

<SCRIPT LANGUAGE-" Java Script") 

window.location="http: //www .example. com/ "</SCRIPT> 

When visitors load the guest book, their browsers receive this tag and immediately begin loading 
the hacked site. With a little ingenuity, the cracker could then take advantage of the visitors' trust of 
your site to extract personal information such as passwords or credit card numbers. 

The solution to this problem is to sanitize the input data. In this case, we want any characters that 
have special meaning to a browser to be translated into something harmless. Luckily, PHP provides 
a way to perform just such a translation. The function htmlspecialchars() converts the charac- 
ters <, >, " , and & to their representations as HTML entities (such as &1 1 ;). We change the first part 
of our program to use this new function as follows: 

<?php if (IsSet($_POST['visitor'])) { 
$visitor = $_P0ST[ ' vi s i tor ' ] ; 
$fp = fopen( "database" , "a"); 
$cl ean_vi s i tor = html speci a 1 cha rs ( $vi s i tor ) ; 
f wri te ( $f p , " <1 i >$cl ean_vi si tor\n " ) ; 
fclose($fp); I ?> 

And we have patched a very significant security hole in our site. 
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Accessing source code 

Even if your PHP source code isn't a trade secret, you should still protect it from exposure to the net- 
work. If an intruder can read your source code, then he or she need not experiment to find a weak- 
ness. Instead, the intruder can simply analyze the code, looking for common mistakes and other 
security holes. In general, the more helpful information you provide to potential intruders, the more 
likely an intrusion. By hiding such tidbits as source code, directory names, or usernames from the 
network, you can reduce the likelihood of an attack. 

c , ' f^"j\j'' " < - )ne handy feature of PHP, error reporting to the browser, is great for development 
-^■ r - w - - because it helps pinpoint problems — but it can be bad for security, because it can also 

give directory paths, filenames, usernames, and potentially database names on error. Minimize the risk 
by turning off error reporting to the browser in production systems, via the d i s p 1 ay e r r o r s direc- 
tive in p h p . i n i . You can still use error reporting to the browser on development systems if you wish, 
although it's safer to use the error 1 og( ) function to write error messages to a log. 

When PHP is used as a web server module, there is little risk of source code being released by the 
web server, as any file with the proper extension is parsed by the PHP module. If PHP is installed as 
a CGI program, however, things are not so simple. 

If you cannot run PHP as a server module, the next most secure setup is to run it as an interpreter 
for CGI scripts, just as you would Perl or Python. 

Place all your PHP programs in the c g i -bin directory for your server or your account and arrange 
for the PHP interpreter to be invoked when they are executed. On Unix, this is done by adding a line 
similar to the following as the first line of every script: 

# ! /usr/local/bin/php 

To use this setup, you must compile PHP with the - -enable -discard -path configuration option. 
This setup has the disadvantage that the URLs for most of your pages contain / cgi - bin/. 

The next most secure setup is a bit more complicated and is actually counter to the recommenda- 
tions of CERT, a respected authority on computer security: We place the PHP interpreter itself in the 
cgi - bin directory. It is usually inadvisable to put an interpreter in the cgi - bin directory, because 
the rules for invoking CGI programs would allow any file on the server to be parsed as a program. 

PHP is written to operate safely from the cgi -bin directory, however, if configured correctly. If 
you intend to use this setup, first carefully read the security and configuration sections of the PHP 
manual, as they may contain important information not available as this book went to press. 

This setup relies upon the web server to redirect URLs of the form: 

http: / / your . server/ program . php 
to URLs of the form: 

http : 1 1 your . ser verl cgi -bi n/php/ program . php 



474 



Securing PHP 



28 



The precise directives that will cause your web server to do this vary. For Apache they are: 

Action php-script /cgi-bin/php 
AddType php-script .php 

If you are using Apache, be sure to compile PHP with the - - enabl e - force -cgi - redirect con- 
figuration option. This option utilizes a feature specific to Apache to prevent PHP from executing 
when invoked by URLs of the second form. Your setup is complete. 

If you are using any other server software, you must compile PHP with the --di sabl e-f orce- 
cgi - redi rect configuration option. PHP cannot distinguish the two types of URLs and serves 
a document of either type. This allows a visitor to view files without regard for web-server-based 
access restrictions. Assume, for example, that the URL www . exampl e . com/top/secret/hush 
. php has access restrictions placed on it. A cracker could use the URL www . exampl e . com/ 
cgi -bi n/php/top/secret/hush . php to read the file anyway. 

In this case, the web server is giving PHP the path name / top/ sec ret/ hush. php. PHP deter- 
mines the location of the program file by prepending the configuration value doc_root to the 
given path name. By default, this value is the same as the web server's document root (the directory 
corresponding to www . exampl e . com/). Setting doc_root to another directory will limit PHP to 
programs in that directory and its subdirectories instead of the entire collection of web server docu- 
ments. Any visitor may access any of the PHP programs by the method just described, however, 
without regard for web-server-based access controls. Be careful! 

Reading arbitrary files 

A few common PHP programming mistakes can make it easy for a hacker to read almost any file on 
the server. Study the following page: 

<HTML> 

<HEADX/HEAD> 
<B0DY> 

<?php if (IsSet($_POST['poem'])) { 
$poem = $_P0ST[ ' poem ' ] ; 
$fp = fopen($poem, "r"); 
print (fread($fp, f i 1 es i ze ( $poem ) ) ) ; 
f cl ose( $fp) ; 
) ?> 

<HRXFORM>Pi ck a poem: 

<S E LECT NAME="poem"XOPTION VALUE=" jabb. html ">Jabberwocky 

<0PTI0N VALUE="graves . html ">Cat-Goddesses</SELECT> 

<I NPUT TYPE="SUBMIT" VALUE="Show Me"X/F0RM> 

</B0DY> 

</HTML> 

This simple program displays a number of poems, selectable from a pop-up menu given in the form 
near the end. Invoke the security mantra: Don't trust the network. Clicking Show Me on this page 
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results in URLs such as poetry . php?poem=g raves . html . A cracker may substitute the filename 
of some more sensitive file, such as poetry . php?poem=/etc/passwd. The program, as given, 
would dutifully serve up the Unix password file, possibly enabling the cracker to break into a visitor 
account and do further damage. 

The following is an appropriate solution to this problem: 

<?php if (IsSet($_POST['poem'])) ( 
$poem = $_P0ST[ ' poem ' ] ; 
switch ($poem) ( 
case " j a b b " : 

$poem_file = "jabb.html"; 
break ; 
case "graves": 

$poem_file = "graves.html"; 
break ; 

) 

if (IsSet($_POST['poem_file'])) { 
$poem_file = $_P0ST[ ' poem_f i 1 e ' ] ; 
$fp = f open ( $poem_f i 1 e , "r"); 
print (fread($fp, f i 1 es i ze ( $poem_f i 1 e ) ) ) ; 
fcl ose( $fp) ; 
} 

1 ?> 

The advantage of this method is that it explicitly lists the acceptable inputs and gracefully handles 
unacceptable inputs. If there were more poems to be processed, the switch statement could be 
replaced with a database query, where failure of the query indicates invalid input. 

This is not a good solution: 

<?php if (IsSet($_POST['poem'])) ( 
$poem = $_P0ST[ ' poem ' ] ; 

if ( !strstr($poem, "/") && ! st rst r ( $poem , "\\")) { 
$fp = fopen($poem, "r"); 
print (fread($fp, f i 1 esi ze( $poem) ) ) ; 
fcl ose($fp) ; 

} 

) ?> 



The second conditional in this code segment checks for pathname separators in the given filename. 
This program explicitly describes a set of unacceptable inputs and considers anything else accept- 
able. It depends on the programmer imagining and checking for every possible undesired input. In 
this case, the programmer has missed something by making the implicit assumption that no sensi- 
tive files are stored in the same directory as the script. 

What if a file that should be private escapes your server anyway? There is a chance that some mis- 
configuration (perhaps by someone else) or an unnoticed security hole will render some or all of 
your server's files publicly accessible. 
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PHP allows you to explicitly specify the set of directories in which files can be opened with the con- 
figuration value open_basedi r. See Chapter 29 for more information on the PHP configuration file. 
This configuration value can be useful to prevent access to entire directories and is a good way to 
minimize the damage. 

Many sensitive files, however, must be opened from PHP programs as visitors access the site. A 
common example is a password file. Access to such a file cannot be blocked with open_basedi r, 
but the sensitive information it contains can be encrypted to render it useless to anyone who may 
steal it. 

A password-protected site must verify the password given by a visitor wishing to gain access. One 
way to do this would be to store a password for safekeeping in encrypted form and then decrypt it 
when we need to compare it to the user-supplied password. The problem is that if we can decrypt 
the password, others may be able to decrypt it too. Also, we would have to make sure that no one 
could see the password after we decrypted it for comparison. Instead, we can use an encryption 
function that only goes one way and is easy to use for encryption, but that can't be decrypted. 
Rather than decrypt a stored password and compare the decrypted versions, we encrypt the given 
password and compare the encrypted passwords. Unix uses this strategy with its own password 
file, /etc/passwd, and PHP allows programmers to use the same encryption function for their own 
password files. 

The function crypt ( password , salt) encrypts the given password. The salt adds an extra bit of 
chance and should be chosen randomly when the password is first recorded. (PHP chooses a random 
salt if this parameter is omitted.) The function returns the concatenation of the salt value and the 
encrypted version of the password. The following function will create a new password for a visitor: 

function new_pw( $gi ven ) { 
return crypt ( $gi ven ) 

) 

And this function will compare a password given by a visitor with a stored, encrypted password: 

function veri fy_pw( $gi ven , Istored) { 

$salt = substr($stored, 0, CRYPT_SALT_LENGTH ) ; 
$gi ven_encrypted = crypt( $gi ven , $salt); 
return ($stored == $gi ven_encrypted ) ; 

) 

Running arbitrary programs 

It's every system administrator's worst nightmare. The server's running more slowly than usual. A 
look at the running programs on the server reveals that a program entitled crack is burning 98 
percent of the processor's time. Most likely, this program has been placed here by a cracker who is 
using it to decrypt (crack) passwords. The administrator logs in to kill the offending program but 
finds that his password is incorrect. His server has been root compromised, and there is no telling 
how much damage has been done. 
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Social Engineering 

5oc/a/ engineering is an often overlooked part of cracking. Sometimes it's easier for crackers to extract infor- 
mation (particularly passwords) from human beings than from computers: 

Cracker: Hi, John, this is Gary in the IT department. When was the last time you used your company 
account? 

John: Well, I entered a few new purchase orders about an hour ago. 

Cracker: Well, John, I'm afraid your account has been compromised. Some of the information in it may 
have been lost. This could cost the company millions if we don't catch the intruder quickly. We need 
to open your account and assess the damage immediately. Can you give me your password? 

John: Sure, it's . . . 

Worse yet, sometimes forgetful visitors note their passwords on scraps of paper in their desks! A determined 
cracker can easily find a job as a night janitor and look for such notes. Many famous crackers were more notable 
for their social engineering and research skills than their ability to write code to compromise systems. 



In a compromise such as this, an intruder gains interactive access to the server, usually via a Unix 
shell or MS-DOS command line. Clearly, this is the most difficult type of heist to pull off, but it also 
bears the greatest reward. Once inside a server, the cracker has virtually unlimited power to bring 
down the server, steal or modify information, or make use of the server's computational power for 
further wrongdoing. Worse yet, a truly skilled cracker can conceal his or her steps by editing log 
files and erasing any temporary files he or she has created. 

PHP has several program execution functions: system( ), exec( ), popen( ), passthru( ), and the 
back-tick C ) operator. As an example of the use of one of these functions, the following page returns 
the Unix finger information for a visitor specified through an HTML form: 

<HTML> 

<HEADX/HEAD> 
<B0DY> 

<F0RM>Get information on < I N PUT TYPE="TEXT" NAME="username"> , 

<INPUT TYPE="SUBMIT" VALUE=" PI ease" ></ FORM) 

<?php if (IsSet($_POST['username'])) ( ?> 

<Hl>Results for <?php echo $_P0ST[ ' username 1 ] ; ?></Hl> 
<pre><?php system( "f i nger " . $_P0ST[ ' username ']) ; ?></pre> 

<?php ) ?> 

</B0DY> 

</HTML> 

The program, as given, takes a username from the HTML form and executes the Unix program finger 
to look up information about that user. You should hear Don't trust the network repeating loudly in your 
head. Unix commands are separated by a semicolon, so anything following a semicolon in the string 
passed to system( ) is treated as a new command. This new command is executed with all the permis- 
sions of the user under which the web server is running. 
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Under Unix, the command "rm - rf /" will delete all files on the server. Imagine the damage if an 
ill-intentioned visitor typed " ; rm - r f / " into the form and clicked Please. 

The best solution to this problem is to filter out everything but valid usernames before invok- 
ing finger. This requires specific knowledge about username formats on your server, so we 
do not present an example here. PHP presents a solution that is almost as good. The function 
escapeshellcmdO will sanitize a string for use in a program execution command, rendering 
harmless any special characters such as the semicolon. We replace the line invoking sy stem( ) in 
the preceding code snippet with: 

<pre><?php 

system( escapes hel 1 cmd (" fi nger " . $_P0ST[ ' username '])) ; 
?></pre> 

Magically, no value the visitor may enter can result in arbitrary programs being executed. This does 
not, however, prevent the visitor from providing unexpected input to finger. Although finger 
does no harm if given incorrect input, other programs may not be so forgiving. If in doubt, err on 
the side of caution! 

To minimize the damage of a compromise of this sort, most modern web servers run as a dummy user 
(often called nobody on Unix systems). This user has only the permissions required to run the web 
server (and any PHP scripts) and read and write the necessary files. But remember, any databases 
or files that your scripts can modify are modifiable by this user, and thus they are vulnerable if an 
attacker can run arbitrary programs. 

Viruses and other e-critters 

Visitors trust software coming from a trusted site. If your site allows visitors to download files 
uploaded by other visitors, you should warn your visitors to check files for viruses before running 
them, and you should consider periodically scanning the files on your server for viruses as well. 
This is a hard problem to solve, particularly with the possibility of embedding viruses in such seem- 
ingly harmless files as word processor documents. Indeed, Microsoft was caught in this very bind 
when it inadvertently released a CD-ROM with a Word document containing the Melissa virus. 




f i'T r { F ^ ^ ee tne sect ' on "Site defacement" at the beginning of this chapter for other ways that 
J ' your visitor may inadvertently receive malicious code. 



FYI: Security Web Sites 

If you are losing sleep after reading this chapter, fear not. Every administrator and site designer 
around the world is grappling with the same issues, and there is a strong feeling of solidarity among 
computer security professionals. Many web sites are devoted to computer security, and almost all 
of them contain full descriptions of recent security incidents and ways to protect your system from 
duplicate attacks. Some are designed for security professionals, whereas others have the cracker in 
mind. Either way, the information they provide is useful and often very interesting. 
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System Administrators 

System administrators, also called sysadmins, are the folks who make sure the computers we all use keep on 
computing and that the Internet keeps on networking. Their jobs are shrouded in mystery: They hold the 
keys to the mysterious "machine room" where all the critical servers are stored. It's not unusual to see them 
hurrying into the office at midnight, surely to avert some crisis that could bring the company to its knees. 

Sysadmins are also a very cautious lot. They tend to program their servers to report any unusual activity imme- 
diately (often to the large-screen alphanumeric pager they carry at all times) and to take swift, decisive action 
against anything they deem improper or unsafe. 

A professor in a Computer Science department once asked his students, as homework, to break into his Linux 
desktop. To make things a little easier, he gave the encrypted text of his password (see the description of 
crypt ( ) in the section "Reading arbitrary files"). In a testament to the security of the Unix crypt ( ) func- 
tion, none of the students cracked his desktop. Several of his students were denied access to their campus 
accounts, however, and questioned by university officials because they were running computationally expensive 
programs named crack! 

If you aren't your own system administrator, but you are concerned about the security of your site, it is probably 
a good idea to befriend your local sysadmin. He or she can sometimes suggest ways to make your site more 
secure and can also be an enormous help in recovering from an incident. 



Begin your explorations by checking out these sites. 

■ Computer Emergency Response Team (CERT) (www . cert . org): CERT is one of the 
most popular repositories of official descriptions of security incidents. It publishes adviso- 
ries on all sorts of security issues, including very clear descriptions of the problem, vulner- 
able systems, and possible solutions. 

■ Security-focus.com (www . securi tyf ocus . com): Security-focus.com provides a great 
deal of information on all aspects of computer security, from the legal and political to the 
technical. It also hosts the well-known security mailing list, BugTraq (which can be found 
under Forums). 

■ Insecure. Org (http://insecure.org): Insecure. Org is a fairly well-established site that 
is not afraid to make cracking tools available and to discuss the nitty-gritty details of many 
"exploits." This site can be extremely useful if you want to try to break into your own site. 



Summary 

For any significant web site, security is a crucial part of the site's implementation. You should take 
extreme care to secure your server from attack and also be sure to protect your visitors' private 
information from prying eyes. In a time of enormous growth for online businesses, publication of a 
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story about a major security breach can destroy visitors' confidence in your site, driving them to the 
competition and possibly leaving your site to evaporate as quickly as it appeared. 

In this chapter, we've driven home three basic lessons. 

1 . Don't trust the network. Every byte of data that comes from the Internet should be treated as 
potentially hazardous. Be as restrictive as possible in defining the inputs you allow. Prefer 
the solution that lists the acceptable inputs to the one that lists the unacceptable inputs. Be 
sure that your web server configuration does not allow clients to view your source code or 
to work around your access restrictions. 

2. Minimize the damage. Wherever possible, make sure that the damage possible from a par- 
ticular type of security breach is minimal. Encrypt sensitive data. If you run your own web 
server, make sure it is running as a dummy user. 

3. Finally, if you run your own server, spend some time breaking into it. If you're successful, then 
you've identified a vulnerability that you can patch before an intruder finds it. If you're 
unsuccessful, you've learned something about your server, and your security precautions 
have weathered a good test. If you don't run your server, find out who does, and see what 
he or she can tell you about your site's security. 
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In this chapter, we discuss the many configuration options available 
with PHP, particularly the Unix Apache module version, in some detail. 
The goal is for you to better understand the tradeoffs of each capability 
you may enable or disable and the capabilities that may affect each other. 
We also touch on ways you can measure and improve the performance of 
your PHP scripts. 



Viewing Environment Variables 

To see any of the settings discussed in the following section, you have only 
to use the phpi nf o ( ) function in a valid PHP script. This function begins 
with a quick recap of the PHP version, your platform, date of build, and 
compile-time options; it then moves methodically through your PHP set- 
tings. You will also see some information about your web server settings 
and environment variables. 

The output of the phpi nf o ( ) function is a potential bonanza for crack- 
ers, so you shouldn't leave it sitting around on a production server. With 
the release of 5.2.1, phpi nf o( ) includes a META tag for robots that causes 
a web spider honoring the robots protocol not to index a phpi nf o ( ) file. 
Nevertheless, because there's nothing that requires adherence to the robots 
protocol, this should not be relied on as a security measure. 



IN THIS CHAPTER 



Viewing environment variables 

Understanding PHP 
configuration 

Improving PHP performance 
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Understanding PHP Configuration 

Like most of the best open source software packages, PHP is highly configurable. It's left up to you, 
the individual PHP user, to find your own balance among the competing virtues of power, flexibil- 
ity, safety, and ease of use. 

Configuration is difficult to describe fully because there are so many possible combinations of 
options. In some cases, there is an obvious conflict between two configuration directives — you 
simply have to choose one or the other, end of story. In other cases, you can have both but may need 
to remember some workarounds. We try to point out as many of these implications as we can, but 
no one can honestly claim to have tested every possible combination. 

The Windows version of PHP now ships with the most popular extensions (for example, MySQL) 
compiled in and a startling number of shared libraries (. d 1 1 s) bundled with PHP itself. Many of 
these libraries have to be built from Unix source, so this effort represents a truly amazing amount of 
unremunerated, thankless work from the PHP build team. 

The truth is that the PHP build for Windows (the so-called manual installation, not the installer 
version) now offers almost all the functionality of Unix builds with much less effort. Windows users 
only need to worry about the variables that can be set with the p h p . i n i file — not all of which are 
applicable to Windows versions of PHP anyway. If you only use PHP on Windows, feel free to skip 
down to the "The php.ini file" section of this chapter, with a glance at the "Apache configuration 
files" section if you run on Apache. 

Unix users have a more specific palette of options. To take full advantage of this power, you need to 
clearly understand the various means by which you can analyze and control your PHP installation. 
The three most important on the Unix side are: 

■ Compile-time options 

■ Web server configuration files 

■ The php.ini file 

A few things can also be controlled with runtime options, system settings, or the presence/absence/ 
configuration of other software packages. 

Compile-time options 

During the configure/make process, PHP allows you to specify a number of specific flags. This 
causes the appropriate extensions to be built into your custom version of the PHP module or binary. 
None of the information in this section is relevant if you are running a precompiled binary (for 
example, Windows, Mac OS X, or RPM build). 

It's important to understand that most compile-time options are merely necessary preconditions 
for using a particular function set — but that this capability can still be turned on or off, or impor- 
tant configuration options set, in the php.ini file. The compilation step and the configuration file 
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work together. Think of it this way: You must compile with the flag to use the functionality, but you 
needn't use the functionality just because you compiled with the flag. 

If you fail to employ the appropriate compile-time option, you get an undefined-function 
fatal error. This error is almost never seen outside of user-defined functions for any other 
reason, so it should be considered a red flashing light that you need to check your compilation options. 
Thankfully, you can retrieve your previous options with phpi nf o ( ) and then simply add the new fea- 
tures you want, should a recompile ever be necessary. 

Most compile-time options are pretty self-explanatory. You merely install the required libraries, 
build PHP with the - -wi th - [ 1 ibrary][=DIR] flag and, in some cases, set a configuration option 
in php . i ni . In the following sections, we will mention only common cases that require special 
treatment of some kind. 



Remember that all third-party servers and libraries that you plan to use with PHP must be 
downloaded and installed before you attempt to build PHP. This means the web server, a 
database server, mail, and LDAP servers, XML, encryption, graphics, and bcmath libraries must all be 
in place before PHP. 



--with-apache[=D!R] or -with-apache2 = [DIR] 

This flag causes PHP to be built as a static Apache module. You must use - -with-apache2 if you've 
ventured into the newest Apache series. Even though the Apache module version is now by far the 
most popular build, the PHP developers have chosen to leave the CGI build as the default choice. If 
you forget this (or the --wi th-apxs) flag when trying to make a static Apache module, you will end 
up with the CGI version. 

You almost certainly want to set the Apache base directory parameter because ma ke may default 
to some unexpected location. Remember that Apache installs in different default directories in the 
source versus RPM builds — so if you've previously installed an httpd via RPM (perhaps as part of 
a Red Hat Linux installation), you should uninstall the package and leave a clean background for the 
source build you need now. 

A static Apache build will have to be recompiled every time you change PHP versions. Apache 
server, at this point, changes rather slowly, whereas PHP adds new extensions and releases patches 
rather frequently, so this may be a significant factor in choosing the a pxs build instead. 

--with-apxs[=DIR] or --with-apxs2[=D!R] 

This flag specifies that the PHP module be built as a dynamic Apache module. This saves disk space 
for Apache, and some people claim the build is easier. The main value of the apxs build is that you 
will be able to swap PHP modules (while upgrading, for instance) without recompiling Apache. If 
you upgrade frequently, or if you enjoy trying out experimental builds, this is the best option. 



Remember that you can build PHP with either the - -with-apacheor withapxs 
flags, not both. 
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--with-[database][=DIR] 

AH the databases supported by PHP use a similar compile-time flag. The directory need only be 
specified if it is not the default installation directory. For more information on choosing a database 
for use with PHP, see Chapter 11. The specific flags and default directories are listed in Table 29-1. 



TABLE 29-1 



Database Compile-Time Information 



Database Name 


Default Directory 


Flag Syntax 


Adabas D* 


/usr/1 ocal 


--with-adabas[=DIR] 


DBase 


bundl ed 


- -enabl e-dbase 


Filepro 


bundl ed 


--enable-filepro 


IBM DB2 


/home/db2i nstl/sqllib 


--with-ibm-db2[=DIR] 


Informix 


no default 


- - wi t h - i n f o rmi x [ =D I R] 


iODBC* 


/usr/1 ocal 


--with-iodbc[=DIR] 


mSql 


/usr/1 ocal /Hughes 


--with-msql [=DIR] 


MySQl < 4.1 


/usr/1 ocal/ my sql 


--with-mysql [=DIR] 


MySQL 4.1 and 
above 


/usr/1 ocal/ my sql 


- - wi th -rnysql i [=D I R] 


Oracle 


ORAC LE_H0ME 


--with-oci8[=DIR] 


PostgreSQL 


/usr/1 ocal /pgsql 


--with-pgsql [=DIR] 


SAP DB 


/usr/1 ocal 


--with-sapdb[=DIR] 


Solid* 


/usr/local/solid 


--with-sol id[=DIR] 


Sybase 


/home/sybase 


- -wi th-sybase [ = DI R] 


Sybase-CT 


/home/sybase 


--with-sybase-ct[=DIR] 


SQLite 


Bundl ed 


--with-sql ite 



The databases marked with an asterisk use ODBC-based interfaces. These ODBC choices are mutu- 
ally exclusive — you must limit yourself to a maximum of one. 

Each database mandates slightly different configuration options in p h p . i n i or other configura- 
tion files. Oracle, for example, has its own environment variables that obviate PHP settings. Sybase, 
Oracle, and some other databases escape single quotation marks with single quotation marks, which 
requires the magi c_quotes_sybase option in php . i ni. MySQL allows you to specify a default 
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hostname, username, and password — not at all a good idea unless you understand the security 
implications! Most of these options are standard and self-explanatory, however, and they have little 
effect on other parts of PHP. 



--with-mcrypt[=DIR] 

This flag builds in the mc ry pt library, which includes many of the most popular open cipher algo- 
rithms, mcrypt is available for download at http : / /mcrypt . sourcef orge . net. 

There is no documented default directory, although PHP can probably find the one mentioned in the 
1 i bmcrypt documentation. 1 i bmcrypt must be compiled with the - - di s a ble-posix- threads 
option. See Chapter 28 for more information on using PHP's cryptography capabilities. 



--with-java[=D!R] 

This flag builds Java support into PHP. The D I R path should be set to the location of your JDK, and 
the Java settings in p h p . i n i must all be set correctly. This extension cannot be used with a static web 
server build (for example, - -with-apache), and this flag will probably not work correctly with Solaris 
versions of PHP and Java. Please see the Java extension README in / p h p_ [ b u i 1 d_di rectory] / ext/ 
Java for more information. 

There is an alternate method of accessing Java from PHP: integrating PHP into a Java servlet environ- 
ment using a SAPI module. You might want to do this if you use Java extensively, as it is the more 
efficient method. If you choose the servlet integration method, you do not need this extension. See 
Chapter 38 for more on using Java with PHP. 



--with-xmlrpc 

This flag builds Dan Libby's XML-RPC and SOAP implementation into PHP. The XML-RPC package 
now comes bundled with PHP, so you do not need to specify a directory. 

| r ' y O 'j .R ^ ? ^° ' earn more aDOut XML-based Web services and PHP, see Chapter 41. 



--with-dom[=DlR] 

This flag builds with DOM XML support, using the GNOME XML library (a.k.a. 1 i bxml , gnome -xml ). 
The D I R path should point to your 1 i bxm 1 installation; if you don't set this value, it defaults to / u s r . 
You can download and learn more about GNOME xml from www . xml soft . org. 

Very common shared libraries, such as 1 i b j peg, can cause fatal problems at PHP 
compile time even if you correctly set the directory paths in all the compile-time flags. 
Common issues include PHP looking for the files in the wrong place, incorrect versions of these librar- 
ies already being installed on your machine, or libraries having been built in a form inaccessible to PHP. 

The solution to most of these problems is to upgrade all such shared libraries to the latest version. 
However, if your client applications are old, this may break them. A possible workaround is to tempo- 
rarily rename the installed versions of your shared libraries, so they cannot be found by PHP; compile 
the new versions in different locations; compile PHP using these directory paths, then rename your old 
versions to their original names. Take good notes if you try this! 
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--enable-bcmath 

This option builds support for arbitrary-precision mathematics from a bundled library. You can set 
the number of decimal places in p h p . i n i . 

—enable-calendar 

This option builds support for calendar conversion functions (for example, Jewish to Julian) from a 
bundled library. 

--with-config-file-path = D!R 

This option allows you to specify the location of your p h p . i n i file. You need to use it only if you've 
deliberately moved it away from the default location, / usr/local/lib. 

--enable-url-includes 

This option allows you to include or require and execute files from remote HTTP or FTP servers, like 
this: include(http://remotehost/include.php). This functionality should be carefully con- 
sidered, as it has horrible security implications. If you merely want to read in HTML files from other 
servers, you do not need this flag. 

--disable-url-fopen-wrapper 

This flag turns off the default capability to open files on remote HTTP and FTP servers, like this: 
fopen(http://remotehost/include.php). 

CGI compile-time options 

All compile-time options just described are available for the CGI version, except for the module- 
specific flags (for example, --with-apache, - -wi th-apxs). 

Most users today who use PHP's CGI mode are interested in using it as a standalone binary, similar 
to Perl, rather than for web development. If this is the case, safe mode is probably beside the point. 

--with-exec-dir[=D!R] 

Another compile-time option relating to safe mode is - -with-exec-dir. This option sets the 
default safe-mode execution directory to / usr/local/bin, but that can be changed with the 
saf e_mode_exec directive in php . i ni . Remember you can only run programs from this single 
directory under safe mode. 

--enable-discard-path 

If you'd like to place the CGI version of PHP outside the web tree and call it as you would a Perl CGI 
script (such as with #!/usr/local/bin/phpas the first line of each script), you need to specify 
this compile-time flag. You must also make all PHP CGI scripts executable. 
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--enable-force-cgi-redirect 

This flag is a security must for the CGI module. It prevents browser users from calling CGI-bin files 
directly, thereby bypassing Apache security settings. This is an Apache-specific configuration directive; 
don't bother trying to enable it if you are running on a different web server or as a standalone binary. 

Apache configuration files 

If PHP is used with Apache as a module or with CGI, much of PHP's basic file-serving capability is 
determined by Apache's configuration files. The main ones from recent versions of Apache Server 
are the httpd . conf file for global settings, and the . htaccess file for per-directory access settings. 
Older versions of Apache split up httpd . conf into three files (access . conf, httpd . conf, and 
s rm . conf), and some users still prefer this arrangement. 

In PHP3, there were specific Apache configuration directives that could substitute for almost 
every php . i ni setting. For example, instead of setting Engine = On in the first substantive line of 
php . i ni , you could put php3_engi ne on in an. htaccess file for a similar effect. As the num- 
ber of PHP configuration directives increased, however, people decided that too many flags were 
cluttering up Apache's namespace. The naming scheme has been generalized, therefore, to encom- 
pass these four basic, configurable directives: 

■ php_value name val ue: Sets value of variable. 

■ php_flag name on j of f: Sets Boolean. 

■ php_admi n_val ue name val ue: Sets value of variable. Can only be used in main Apache 
configuration file(s) rather than .htaccess. 

■ php_admi n_f 1 ag name on | of f: Sets Boolean. Can be used only in main Apache con- 
figuration file(s) rather than .htaccess. 

An example would be magic quotes for GET, POST, and COO K I E variables. You can use php_f 1 ag 
with the name of the variable, like this: 

php„flag magi c_quotes_gpc off 

If this is all too confusing, don't worry: The new-style Apache configuration directive naming only 
applies to settings you can change in php . i n i anyway. 

Apache server has a very powerful, but slightly complex, configuration system of its own. Learn 
more about it at the Apache web site: www .apache.org. 

The following headings describe settings in httpd. conf that affect PHP directly and cannot be set 
elsewhere. 

Timeout 

This value sets the default number of seconds before any HTTP request will time out. If you set 
PHP's max_executi on_t i me to longer than this value, PHP will keep grinding away but the user 
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may see a 404 error. In safe mode, this value will be ignored; you must use the timeout value in 
php . i n i instead. 

DocumentRoot 

DocumentRoot designates the root directory for all HTTP processes on that server. It looks some- 
thing like this on Unix: 

DocumentRoot "/ us v I local /apache_l .3.6/htdocs" 

It looks like this on Windows: 

DocumentRoot "C:/Program Fi 1 es/Apache/htdocs / " 

The document root can be almost any directory — it needn't be in the Apache installation directory. 
You can specify a subdirectory of this as the PHP document root, using the doc_root setting in 
php. i n i . In this case, HTML files would be served out of the Apache document root and its subdi- 
rectories, but PHP would be parsed only in the specified PHP directory and its subdirectories. 

AddType 

The PHP MIME type needs to be set here for PHP files to be parsed. 

Remember that you can associate any file extension with PHP; many administrators set the . php3 
and . html types for backward compatibility — but if you wanted to, you could have PHP parse files 
called filename.asporfilename.jsp. You can also add multiple types for different versions 
of PHP. The following are sample AddType lines; the first one is the most common for PHP4 and 
above, but you can add as many of the others as you wish. 

AddType appl i cati on/x-httpd-php .php 

AddType appl i cati on/x-httpd-phps .phps 

AddType appl i cati on/x-httpd-php3 .php3 .phtml 

AddType appl i cati on/x-httpd-php .html 

You can also set this on a per-directory basis with .htaccess, simply by adding type lines to 
. htaccess files. PHP files are then parsed only in one directory of your site (for instance, in a 
forum folder). Alternatively, you can set up a directory with archived versions of files that may 
have old extensions — so just in that directory, Apache allow files with the .phtml extension to 
be parsed. 

Action 

You must set this line for the CGI version of PHP with Apache, generally used with Windows. You 
do not need to set this line for the module version of PHP. 

Action appl i cat i on/x- httpd-php4 " /php/php . exe " 



490 



Learning PHP Configuration 



LoadModule 

You must uncomment this line for the Windows apxs module version of Apache with shared object 
support: 

LoadModule php4_module modul es/php4apache . dl 1 
or on Unix flavors: 

LoadModule php4_modul e modul es/mod_php . so 

AddModule 

You must uncomment this line for the static module version of Apache. 
AddModule mod_php4.c 

The php.ini file 

The PHP configuration file, php . i ni , is the final and most immediate way to affect PHP's function- 
ality. Important changes are frequently made in the structure of this file, so if you haven't bothered 
to really look at every line recently, now may be a good time. 

The php.ini file is read each time PHP is initialized — in other words, whenever h 1 1 p d is 
restarted for the module version or with each script execution for the CGI version. If your change 
isn't showing up, remember to stop and restart httpd. If it still isn't showing up, use phpinfo( ) 
to check the path to php.ini (near the top of the file); if necessary, recompile the code with the 
--with-config-file-path flag or just move php.ini to wherever PHP expects to find it. 

"-- o-^jv" What happens if PHP can't find php . i ni? Under Windows, right up until the formal 
•■"••^^ release of PHP4, you used to get an "unable to parse configuration file" fatal error. Under 
Unix and now under Windows as an ISAPI module, interestingly enough, you get no warnings or errors 
— PHP carries on with default settings, which are the same as if you had not changed any settings in 
php . i ni di st. You need to install php.ini only if you want to change the default settings. 

The configuration file is well commented and thorough. Keys are case-sensitive, keyword values are 
not; whitespace, and lines beginning with semicolons are ignored. Booleans can be represented by 
1/0, Yes/No, On/Off, or True/False. The default values in php . i ni - di st will result in a rea- 
sonable PHP installation that can be tweaked later. 

What follows are notes explaining the settings in p h p . i n i that are not completely documented in 
the file or the PHP manual's conf i gurati on . html page. 

short_open_tag = Off 

Short open tags look like this: < ? ? > . This option must be set to 0 f f if you want to use XML 
functions. 
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disable functions = [function - !, function2, function3 . . . function/?] 

A welcome addition to PHP4 configuration and one perpetuated in PHP6 is the ability to disable 
selected functions for security reasons. Previously, this necessitated hand-editing the C code from 
which PHP was made. Filesystem, system, and network functions should probably be the first to go 
because allowing the capability to write files and alter the system over HTTP is never such a safe idea. 

max_execution_time = 30 

The function set_t i me_l i mi t ( ) won't work in safe mode, so this is the main way to make a script 
time out in safe mode. In Windows, you have to abort based on maximum memory consumed 
rather than time. You can also use the Apache timeout setting to timeout if you use Apache, but that 
will apply to non-PHP files on the site, too. 

error_reporting = E_ALL & ~E_NOTICE 

The default value is E_ALL & ~E_N0T ICE, all errors except notices. Development servers should be 
set to at least the default; only production servers should even consider a lesser value. 

error_prepend_string = ["<font color=ff0000>"] 

With its bookend, error_append_stri ng, this setting allows you to make error messages a dif- 
ferent color than other text, or what have you. We recommend setting the value to " <bl i n k> " (and 
e r r o r_a p p e n d_s t r i n g to " < / b 1 i n k > " , of course) for a special treat! The default values result in 
a red error message. Remember to uncomment these if you want to use them — they're commented 
out by default. 

warn_plus_overloading = Off 

This setting issues a warning if the + operator is used with strings, as in a form value. 

variables_order = EGPCS 

This configuration setting supersedes gpc__order. Both are now deprecated along with r e g i s t e r_ 
gl obal s. It sets the order of the different variables: Environment, GET, POST, COOKIE, and SERVER 
(aka Built-in). You can change this order around. Variables will be overwritten successively in 
left-to-right order, with the rightmost one winning the hand every time. This means if you left the 
default setting and happened to use the same name for an environment variable, a POST variable, 
and a C00KI E variable, the COOKI E variable would own that name at the end of the process. In real 
life, this doesn't happen much. 

gpc_order = GPC 

Deprecated. 

auto-prepend-file = [path/to/file] 

If a path is specified here, PHP must automatically 1 ncl ude ( ) it at the beginning of every PHP file. 
Incl ude path restrictions do apply. 
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auto-append-file = [path/to/file] 

If a path is specified here, PHP must automatically i n c 1 u d e ( ) it at the end of every PHP file — 
unless you escape by using the exi t ( ) function. Incl ude path restrictions do apply. 

include path = [D1R] 

If you set this value, you will only be allowed to include or require files from these directories. The 
include directory is generally under your document root; this is mandatory if you're running in 
safe mode. Set this to . in order to include files from the same directory your script is in. Multiple 
directories are separated by colons: .:/usr/local/apache/htdocs:/usr/local/lib. 

doc_root = [DIR] 

If you're using Apache, you've already set a document root for this server or virtual host in httpd 
. conf . Set this value here if you're using safe mode or if you want to enable PHP only on a portion 
of your site (for example, only in one subdirectory of your web root). 

upload_tmp_dir = [DIR] 

Do not uncomment this line unless you understand the implications of HTTP uploads! 

session, save-handler = files 

See Chapter 24 for details on this setting. Except in rare circumstances, you will not want to change 
this setting. 

ignore_user_abort = [On/Off] 

This setting controls what happens if a site visitor clicks the browser's Stop button. The default is On, 
which means that the script continues to run to completion or timeout. If the setting is changed to 
Off, the script will abort. This setting only works in module mode, not CGI. 



Improving PHP Performance 

There are two schools of thought about web performance. The first is that PHP script performance, 
theoretical web server speed, chip clock speed, server RAM, and almost everything else is made 
irrelevant by throughput issues — so why sweat the small stuff? The other is that there's no thrill 
quite like that of shaving a few microseconds off your script execution time. This section is basically 
useless for proponents of the former view. 

Before you can improve your performance, you have to measure it. We use the time-honored pro- 
gramming performance metric: measuring microseconds. Whip up a little function like this: 

function exec_ti me ( ) 

( 

$mtime = explode( " ", mi cnotime( ) ) ; 
$msec = (doubl e)$mtime[0] ; 
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$sec = ( doubl e) $mtime[l] ; 
return $sec + $msec; 

} 



This function just reformats microtime output into a double for easier subtraction. Paste or include it 
at the top of the script you'd like to measure. Now divide the main body of your script into sections 
and scatter calls to exec_t i me ( ) at strategic points, like this: 

<?php 

$start_db_cal 1 = exec_time(); 

$db = mysql_sel ect_db( "test" ) ; 

$result = mysql_query( "SELECT * FROM user 

WHERE ID=1"); 
while (Stestrow = mysql_f etch_a r ray ( $ resul t ) ) ( 
echo $testrow[0]; 

1 

$end_db_call = exec_ti me ( ) ; 

$runtime = $end_db_call - $start_db_cal 1 ; 

echo "Database call and echo took $runtime seconds"; 

?> 



The next time you hit the web page, voila! A self-timing PHP script, at your service. 

n , '■ ' '"--"j Using mi crot i me ( ) to measure PHP tells you only what happens between the time PHP 

begins working on the first measured line of code and the time it finishes working on 
the last measured line of code. It does not tell you how long your web server is taking to spawn a child 
process or your CGI to start up, how much latency your server is suffering from, what traffic conditions 
at your web farm are like, or a lot of other things that affect real-world performance at least as much if 
not more than actual PHP processing time. To find out that kind of thing, you need measuring tools far 
beyond PHP. A good start for Apache on Unix is the program called ab (aka Apache Benchmark tool), 
which ships with Apache. 

Now that you know how long the various parts of your script are taking, you can take steps to 
improve performance. Actually, a little logic should tell you that functions that touch other files or 
call other daemons should take longer than those that are self-contained within a discrete file. So 
database calls, i ncl ude and requi re statements, objects with inheritance, and XML parsing are 
just going to take longer than simple arithmetic or echoing a string. But because these advanced 
functionalities are the best part of PHP, obviously it would be pointless to get rid of them for the 
sake of squeezing out a few more microseconds. 

What you can and should do instead is hunt and destroy gross programming errors that cause 
unnecessary latency. Infinite loops, you know, are never very stylish. If you can notice a script run- 
ning slowly with the naked eye, especially on a localhost, it's cause for concern — whip out the 
microtime and find out where it's going wrong. Pay special attention to known bottlenecks such as: 
using regex instead of the faster, built-in functions such as expl ode ( ) in a tight loop; object-ori- 
ented programming where it's not needed; bad use of SQL; including multiple instances of the same 
files; and long loops. 
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Although it would be better to eliminate all errors in the code itself, you can also help matters by set- 
ting the Apache or PHP timeout and max-memory configuration variables as low as possible. Come 
on — no web page should need a 300-second timeout and you know it. Another configuration set- 
ting that may have a good effect on extremely slow scripts is i gnore_user_abort in php . i ni . 

Recent distributions of PHP have also offered an optimized p h p . i n i that sets variables for maxi- 
mum speed at the possible expense of other virtues. If you choose to use this file, please take the 
time to understand the effects of its changes, as the changes may affect legacy scripts that expect 
HTTP_* variables and other globals. 



Optimizers and Caches 

Until recently, speed-shavers had few options but homemade metrics like the mi crotime( ) func- 
tion just described. But now, intriguing tools are beginning to become widely used to increase PHP 
performance. 

One that is available without cost is the Zend Optimizer. This tool makes multiple passes over a PHP script and 
replaces slower constructs with faster ones that have the same effect. However, the Zend Optimizer is rumored 
to mostly help inexperienced coders: If you already write tight PHP, it may not be able to add much value. 

Another Zend product that promises to affect performance positively is the Zend Accelerator. This product 
apparently compiles and stores a version of each page in memory, reducing disk reads and redundant compi- 
lation and thus speeding Web service. Reliable reports claim that the Accelerator can deliver from two to ten 
times improvement in number of requests handled. Both the Zend Accelerator and the Zend Optimizer are 
available at the Zend web site, www . zend . com. 

There are also optimizing and caching products available without cost. Two popular choices are Nick Lindridge's 
PHP Accelerator (www .php-accelerator.co.uk) and APC (http://apc.communityconnect. com). 
These may be included in PHP 6 or in subsequent point releases, following the initial PHP 6 release. At the 
time of this writing, the final decision hadn't been made. 



Summary 

The good thing and the bad thing about PHP configuration are the same: There are a whole heck of a 
lot of options and more than one way to set many of them. The Unix Apache module is particularly 
rich in choices, but the development team has labored long and hard to make PHP as customizable 
as possible. 

There are three main ways to configure PHP. The first is via build-time flags, which are only avail- 
able to those who build from source. Many of these directives are only necessary preconditions, 
meaning they set default conditions that need to be confirmed or can be reversed elsewhere. The 
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second is via Apache configuration files (httpd.conf and .htaccess), which are only available to 
users of Apache server. The third is via the php . i ni file, which comes with every PHP distribution. 

The php. i n i file experienced a few significant changes with PHP4, but hopefully has stabilized 
somewhat with PHP6 One of the most important is the capability to disable functions on an indi- 
vidual basis. Certain features of PHP3 and PHP2 are beginning to be deprecated in this file, such as 
register_globals. And the p h p . i n i is no longer an absolute necessity on Windows — versions 
of PHP now recognize default values even without the file being present in the Windows path. 

After you've run PHP for a while, you may wish to tune its performance. Beginning with PHP 5 and 
continuing into PHP 6, execution times are considerably faster at the same tasks than earlier ver- 
sions, and in general script execution time isn't the bottleneck to total performance — but you may 
want to maximize the efficiency of your PHP-enabled server anyway. The main tool available to 
measure performance is simply echoing m i c r o t i me ( ) at intervals throughout a script. With this 
simple method, you can try to narrow down and improve the parts of your scripts that are taking 
the most time. This does not measure anything outside PHP that may affect its performance; for 
that, you need external tools such as ab (Apache Benchmark). 

Tools to help speed up PHP are becoming widely available. One of the most intriguing is Zend's 
Accelerator, which promises at a minimum to double pages served on the same hardware. There are 
also alternatives available without cost. 
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Until now, programmers have been very creative in figuring out how 
to deal with error cases within PHP, whether setting and printing 
error strings or using and abusing the limited error reporting system. 
Despite its many useful features, PHP has not contained a good system for 
comprehensively dealing with errors. Fortunately, this changed with PHP5. 



Error Handling in PHP 

If you are familiar with structured programming languages, such as C and 
Java, you have probably grown accustomed to the various built-in objects 
that allow you to handle errors and exceptions. If so, you'll be happy to 
note that PHP5 now includes, for the first time, an exception-handling 
object, and that the syntax is very similar to existing languages like Java. 
In fact, once you learn a bit of syntax you can begin handling errors and 
exceptions much as you have been with other object-oriented languages. 

However, if you have been primarily using PHP, and are unfamiliar with 
other languages, the idea of exception handling may be new to you. 
Exception handling is a powerful tool that you will come to appreciate once 
you understand the concept and put it to good use in your code. This new 
built-in function will enable you to debug error conditions, recover from 
unexpected situations, and present a clean interface to your end users with- 
out printing errors to the screen. 



Errors and exceptions 



IN THIS CHAPTER 



Error handling in PHP 

The Exception class 

The try/catch block 

Throwing an exception 

Other methods of error 
handling 

Logging and debugging 



It is helpful to think of an exception not merely as an error. An exception, 
as the name implies, is any condition experienced by your program that is 
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unexpected or not handled within the normal scope of your code. Generally, an exception is not a 
fatal error that should halt program execution, but a condition that can be detected and dealt with in 
order to continue properly. 

Exceptions, when properly used, can greatly increase the reliability of your application, and cut 
down on debugging headaches. However, poorly handled or ill-defined exceptions can create more 
problems than they solve by obscuring the source of an error. Plan on taking the time to properly 
determine and execute your exception-handling method, and you will be amply rewarded. 

Take a look at some sample code that contains some error detection as it might be handled in PHP4 
or earlier. We are retrieving a POST variable containing a user's ID, which must be at least nine char- 
acters in length and begin with the "usr" prefix. Once the variable is checked for these conditions, 
we pass it to a function that will verify the existence of the user within the site database. 



LISTING 30-1 



Error-handling without exceptions 

<?php 

// include the file which will validate the user ID 
requi re_once( ' i ncl udes/usr_f uncti ons . php ' ) ; 

// retrieve the user ID to validate 
$user_id = $_P0ST[ ' user_i d ' ] ; 

// set the display message based on whether or not the 

// user ID is valid 

if ( ! i s„val i d_user ( $user_i d ) ) ( 

$msg = "Sorry, $user_id is not a valid user ID."; 
) else ( 

$msg = "$user_id is a valid user ID."; 

1 



function i s_va 1 i d_user ( $user_i d ) { 

// return false if the user ID does not begin with "usr" 
$pre_str = "usr" ; 

if ( ( strpos ( $user_i d , $pre_str) === false) | 
( strpos ( $user_i d , $pre„str) != 0)) { 
return false; 

} 

// return false if the user ID is not the proper length 
if ((strlen($user_id) < 9)) I 
return false; 

} 
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if ( val i date ( $user_i d ) ) { 

// user ID was found in the database 

return true; 
) else ( 

// the specified user ID does not exist in the database 
return false; 

} 

} 

?> 



As you can see, any number of conditions might cause the i s_v a 1 i d_u s e r ( ) function to return a 
value of false, only one of which actually pertains to the question of whether the user exists in the 
database. Using exceptions, you can more easily distinguish among types of errors and deal with 
them according to the nature of each error. 

The Exception class 

The new Exception class was built into PHP5 and ready for use with any code on a PHP5 or later 
server. Rather than using Boolean functions as in the preceding example, an instance of Exception 
can be created or thrown within the code. 

Listing 30-2 shows what Listing 30-1 might look like after rewriting to use exception handling. 



LISTING 30-2 



Error-handling using exceptions 

<?php 

// include the file which will validate the user ID 
require_once( ' i n c 1 u d e s / u s r_f u n c t i o n s . p h p ' ); 

// retrieve the user ID to validate 
$user_id = $_P0ST[ ' user_i d ' ] ; 

try ( 

// set the display message based on whether or not 

// user ID is valid 

if ( ! i s_val i d_user ( $user_i d ) ) { 

$msg = "Sorry, $user_id is not a valid user ID."; 
} else { 

$msg = "$user_id is a valid user ID."; 

) catch ( Excepti on $ex) { 

// retrieve the message from the exception object 
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$msg = ( $ex->getMessage( ) ) ; 

) 



function i s_val i d_user ($user_id) ( 

// throw an exception if the user ID does not begin 
/ / with " u s r " 
$pre_str = "usr" ; 

if ( ( strpos ( $user_i d , $pre_str) === false) | 
( strpos ( $user__i d , $pre_str) != 0)) ( 
throw new 

Excepti on ( ' $user_i d does not contain the proper prefix.'); 

} 

// throw an exception if the user ID is not the proper length 
if ((strlen($user_id) < 9)) { 

throw new Excepti on (' $user_i d is less than the 
requi red 1 ength ' ) ; 

} 

if ( val i date ($ use r_i d ) ) { 

// user ID was found in the database 
return true; 

} 

else 

// the specified user ID does not exist in the database 
return false; 

} 



Don't be thrown by the use of the word throw. In this case, it is used to create a new Exception 
object. Now errors that have nothing to do with normal flow are handled as separate exceptions 
rather than mingling with the rest of the application. 

The try/catch block 

Exceptions are caught and handled using a try/catch control construct. You will want to include any 
code that may generate an error or exception within the t ry ( ) construction. Whenever any excep- 
tion is thrown by the code, the t ry ( ) block execution is terminated, and the remaining code within 
the t ry ( ) construction is not executed. The c a t c h ( ) block is then consulted to find the proper 



500 



Handing Exceptions with PHP 



type of exception, and the exception is then dealt with according to the code within that particular 
catch block. We now have different conditions based upon the type of exception that was thrown, 
rather than one general, nonspecific error. 



Throwing an exception 



One of the nice things about using exceptions is the ability to display as much — or as little — 
information as you need. There are several methods available for use with an Exception object, 
which you can use to create your own error messages or to deal with conditions accordingly. 

The following code shows how you might throw and immediately catch a generic exception, and 
then take apart the Exception object to recover the message, the error code, and the originating file 
and line number. 

<?php 
try { 

throw new Excepti on (' Syntax error'); 

) catch ( Excepti on $ex) j 

// the input string passed to the object 
$msg = ( $ex->getMessage( ) ) ; 
// customizable error code 
$code = ($ex->getCode( ) ) ; 

// name of the file that threw the exception 
$fi 1 e = ( $ex->getFi 1 e( ) ) ; 
// line number containing the exception 
$line = ( $ex->getLi ne( ) ) ; 

echo "Error no. $code: $msg in file $file on line $line"; 

} 

?> 

Here, a standard, PHP style error message is displayed. However, you as the programmer can display 
anything that you like or can even change application behavior based on the specific error. 

Note that, although in this example the code that throws the exception is the only thing in the 
block, we could have had arbitrarily complex code that calls a function defined in a different file, 
which throws an exception only some of the time. Whenever an exception is thrown, control will 
revert to the catch block associated with the try. 

Multiple catch blocks can be used to deal successfully with more than one type of exception. We'll 
look at an example in the following section. 
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Defining your own Exception subclasses 

PHP also allows you to define your own classes that inherit from the Except ion class. Now you no 
longer have to rely on the getMessage( ) function for information on the specific type of error that 
was generated. Subclasses can be defined as in the following example: 

<?php 

class CustomExcepti on extends Exception { 

public function construct ( $ message ) ( 

parent: :Exception($message); 

1 

} 

?> 

Let's look at the example covered in Listing 30-3 and consider using custom exceptions. People sign- 
ing in using this code may forget to include the "usr" prefix in their username, so if it's missing you 
might want to try adding it and validating again rather than immediately halting the program. 



LISTING 30-3 



Recovering using custom exceptions 

<?php 

// include the file which will validate the user ID 
requi re_once ( ' i ncl udes/us r_f uncti ons . php ' ) ; 

// retrieve the user ID to validate 
$user_id = $_P0ST[ ' user_i d ' ] ; 

try ( 

// set the display message based on whether or not 

// user ID is valid 

if ( ! i s_val i d_user ( $user_i d ) ) ( 

$msg = "Sorry, $user_id is not a valid user ID."; 
) else ( 

$msg = "$user_id is a valid user ID."; 

} 

1 catch ( Prefi xExcepti on $ex) ( 

// if prefix is missing, try again with proper prefix 
$user_pre = "usr" . $user_pre; 
if ( ! i s_va 1 i d_user ( $user_pre ) ) ( 

// second attempt has failed, retrieve message 

$msg = ( $ex->getMessage( ) ) ; 
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//define custom exception classes 

class Pref i xExcepti on extends Exception ( 

public function construct ( $message ) I 

parent: :Exception($message) ; 



class LengthExcepti on extends Exception { 

function cons t ruct ( Imessage ) { 

parent: :Exception($message) ; 

} 

} 

echo $msg; 

function i s_va 1 i d_user ($user_id) { 

// throw an exception if the user ID does not begin 
/ / with " u s r " 
$pre_str = "usr" ; 

if ( ( strpos ( $user_i d , $pre_str) === false) | 
( strpos ( $user_i d , $pre_str) != 0)) ( 
throw new 

Pref i xExcepti on (' $user_i d does not contain the proper prefix.'); 



// throw an exception if the user ID is not the proper length 
if ( ( strl en( $user_id) < 9)) { 
throw new 

LengthExcepti on (' $user_i d is less than the required length'); 

) 

if ( val i date ($ use r_i d ) ) { 

// user ID was found in the database 
return true; 



else 



// the specified user ID does not exist in the database 
return false; 



I 

?> 
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Note that we attempted to recover from the missing prefix error condition. You can easily deal with 
individual types of errors now that they have been defined separately. 

Limitations of Exceptions in PHP 

The Exception object is completely new in PHP5 and as such is still in the rough stages of develop- 
ment. As of this writing, PHP does not support the use of f i nal 1 y ( ) or t h rows ( ) methods as do 
Java and other languages. Also, unlike other languages, native PHP errors — including errors, which 
are normally printed to the client-side browser — are not yet mapped to exceptions. Because of this, 
for example, a SQL statement error within a try/catch block will not automatically throw an excep- 
tion that can be caught and dealt with. This handy functionality will most likely be included in a 
future version of PHP, so it's worth mentioning and keeping an eye out for. Some of these errors can 
be dealt with using techniques described in the next section. 



Other Methods of Error Handling 

If you're still using PHP4 or an older version, or are not comfortable dealing with classes and objects, 
there are several error-handling functions that have been available in PHP for some time, including 
native PHP errors, defining an error handler, and triggering a user error. 

Native PHP errors 

PHP generates several types of errors, depending on severity. Here are three common types. You can 
find more information at www . php . net/er ror_reporti ng. 

■ Notice: These errors are not serious and do not create a serious problem. By default they 
are suppressed, unless the logging level is changed in the php . i ni file. 

■ Warning: Failed code has created an error, but does not terminate execution. Usually the 
error is displayed, but the script continues to run. (See Figure 30-1.) 

■ Fatal error: A serious error condition has rendered the script unable to run. A fatal error 
terminates the script. (See Figure 30-2.) 

Each type of error is also represented by a constant that can be referred to within your code: E_ 
USEFLNOTICE, E_USER_WARNING, and E_USER_ERROR. The error-reporting level can be manually 
defined within a script, as in these examples: 

//report only fatal errors 
error_reporti ng( E_USER_ERROR) ; 

//report warnings and fatal errors 
error_reporting(E_USER_WARNING | E_USER_ERROR) ; 

//report all errors, including notices and E_STRICT 
error_reporti ng ( E_ALL ) ; 
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FIGURE 30-1 



Native PHP Warning allows the page to finish rendering 
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FIGURE 30-2 



Native PHP Fatal error terminates execution of the page 
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n i f O' 1 ' * Suppressing error reporting to avoid printed errors can lead to hair loss during the 

debugging process! You will instead want to deal with an error handler, for the most part. 

Because notices never make it to the client, and don't impair functionality, you're almost always safe 
in disregarding them for error-handling purposes. Conversely, the custom error handler cannot han- 
dle fatal errors; PHP considers them serious enough to terminate the script, no questions asked. So 
the usefulness of the custom error-handling function is generally limited to warnings. The primary 
use of this function is to avoid printing program-ese error messages for the end user and disrupting 
the flow of the application. 



Defining an error handler 



There's an important question to ask at this point: What information do you want displayed to the 
user when an error occurs? Usually, it's not important, or even preferable, to display details of the 
inner workings of your application to an end user; not to mention that errors look ugly on a web 
page. By creating a function that designs a custom error message, then setting that function as the 
default error handler, you can avoid the awkward and unprofessional display of errors to a user. 

First, let's create a function and determine what information we would like to provide. We will need 
to accept as input parameters the error type, message, filename, and line number. 

<?php 



f uncti on 
C 


error_msg( $err_ty| 


echo 


" < d i v class='error! 


echo 


" <b>Er ror : </b> " ; 


echo 


"<p>"; 


echo 


"We're sorry, but 


" i 


n this page. "; 


echo 


"Please access the 


"< 


/ a > page, " ; 


echo 


"or try again late 


echo 


"</div>" ; 


echo 


"<div class='fineP 


echo 


"Error type: $err_ 


" a 


t line $ e r r_l i n e " ; 


echo 


"</div>" ; 



1 

?> 



We have elected, in this case, to provide information on the specific error and where it occurred. 
Depending on the situation, we may want to provide very little information to the user other than 
the fact that an error has occurred and provide information on what to try next. 

Now that we have defined our custom error handler, we simply need to refer to the function within 
the code using the set_error_handl er( ) function: 

set_error_handl er( "error_msg" ) ; 
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FIGURE 30-3 



A custom error handler preserves the interface 
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With this code in place, all errors that are enabled by the error-reporting level will direct through 
our custom function, with the unfortunate exception of a fatal error. See Figure 30-3 for an example 
of such an error being displayed. 

Triggering a user error 

PHP4 can be used to trigger a user error, which is roughly equivalent to throwing an exception in 
PHP5. An error of any type can be thrown by passing an error message and an optional error-level 
constant: 

<?php 

// trigger a user error if the user id is not valid 
if ( ! i s_val i d_user ( $user_i d ) ) 1 

tri gger_error( " Inval i d user ID", E_USER_WARNING) ; 

} 

?> 
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The triggered error is best used in conjunction with a custom error handler. Once this error is 
thrown, your defined error handler will be used to provide a formatted error message to the user. 
Note that the error-level constant defaults to E_USER_NOTICE, which is ignored unless you have 
specifically set error reporting otherwise. 



Logging and Debugging 

As mentioned earlier, exception handling and error reporting can turn your debugging efforts into 
a nightmare if not executed with care. An error that is difficult to track down can become almost 
impossible when it has been suppressed or rerouted carelessly. With a bit of planning, however, 
exceptions and error handlers can greatly simplify maintenance of an application. 

Previously, we have examined the process of dealing with errors primarily as a means of avoiding 
disruption for the user. The same process can also be applied to enable logging and debugging for 
the programmer. Within your c a t c h ( ) control block, include a call to a built-in function such as 
e r r o r_l o g ( ) , with any relevant information that might aid in the debugging process. Note that 
you might want to explore the use of the getTraceAsStri ng ( ) function which can be helpful 
for logging. 

} catch ( Excepti on lex) ( 

// the input string passed to the object 
$msg = ( $ex->getMessage( ) ) ; 
// customizable error code 
Scode = ( $ex->getCode( ) ) ; 

// name of the file that threw the exception 
$f il e = ($ex->getFil e( ) ) ; 
// line number containing the exception 
$ 1 i n e = ( $ex->getLi ne( ) ) ; 

// write to error log 

$log_msg = "Error $code in $file at line $line: $msg : " . 
time( ) ; 

error_Jog ($log_msg, 3, " /va r/tmp/php_error . 1 og" ) ; 

//print to screen 
echo "Error no. $code: $msg in file $file on line $line"; 

) 

The process is similar when using a custom error handler (as is the aforementioned 
getTraceAsStri ng( )): 

<?php 

function error_msg( $type , $msg, $file, $line) ( 
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// write to error log 

$log_msg = "Error $type in $file at line $line: $msg : " . 
ti me ( ) ; 

$log_path = " /va r/tmp/php_error . 1 og" ) ; 
error_log ($log_msg, 3, $log_path); 

//print to screen 

echo "Error type: $err_type: $err_msg in $err_file " . 
"at 1 i ne $err_l i ne" ; 

} 

?> 

error_l og ( ) accepts one of four integers as the second parameter, which sets the message type in 
conjunction with the third, or location, parameter: 

0: uses the operating system's system logging mechanism 

1 : sends the error to a specified e-mail address (extra headers may be added as a 
fourth parameter) 

2: sends the error through PHP's debugging connection (remote debugging must 
be enabled) 

3 : error message is appended to a destination error log file 

Summary 

Error handling continues to become easier and more uniform with the ongoing development of PHP. 
The Except i on class provides a means of separating error conditions, or exceptions, from the flow 
of the application. Using the try/catch block and custom- defined Except i on subclasses, errors can 
be intercepted and even recovered. 

Previous versions of PHP also provide a measure of error handling and reporting. User errors can be 
triggered as an alternative to throwing an exception, and custom error handlers can provide a better 
user experience as well as useful debugging information. Logging and debugging are crucial to suc- 
cessful exception and error handling. 
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Debugging — finding and eliminating errors — is part of software 
development. As a PHP programmer, you should be aware of all 
the tools available to you as you seek to eliminate malfunctioning 
elements in your software systems. 

There are many such tools, not least because PHP applications usually rely 
on the capabilities of several servers (such as an HTTP server and a data- 
base management server), each of which typically comes equipped with its 
own logging and reporting capabilities with which it keeps its users hip to 
what's happening. Plus, PHP has a considerable error-reporting facility of 
its own (you can choose to have error messages printed alongside normal 
output or logged to a file for more discreet analysis). The language also has 
a number of functions with which you can have your programs generate 
custom error reports, and at the very least you can use conditional print 
statements to monitor the activity of programs (and the values of variables 
within them) as they execute. 

On top of the built-in error-reporting capabilities of PHP and its supporting 
technologies, PHP programmers now have access to the sorts of debugging 
tools that programmers working with other languages have had for years. 
Chief among these is the Zend debugging environment, which allows you to 
monitor variable values, set breakpoints, and step through programs at any 
pace you like. Though the Zend debugging environment won't be covered in 
this chapter, you can find out more information about it at www . zend . com. 

This chapter aims to introduce you to the tools and techniques available to 
you as you work to perfect your PHP software. 



TIN THIS CHAPTER 



Using web server logs 



PHP error reporting 



Error-reporting functions 



Diagnostic print statements 
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General Troubleshooting Strategies 

The two basic elements of a debugging effort are figuring out what's wrong, and then fixing it 
(without breaking something else as a side effect of your solution). It doesn't matter whether you're 
diagnosing a PHP program, a telephone switch, an electronic circuit, or a Buick — certain principles 
apply regardless. Bear these ideas in mind as you try to figure out what ails your software. 

Change one thing at a time 

It's a basic rule of experimentation: You can't be sure what caused a given effect if there are multiple 
variables. Make a single change, then examine the output and see if the unwanted behavior is fixed. 
If not, try one more change (possibly changing the first one back to the way it was). 

Try to isolate the problem 

If you can narrow the problem down to a single library or function, you've made significant progress 
in locating the cause. Use special va r_dump( ) , echo( ) , and pr i nt_r ( ) calls to output trace infor- 
mation frequently. This will allow you to see when troublesome changes are taking place and when 
variables stop holding the values you think they're holding. 

You can also use a visual debugger (like Zend Studio) to monitor programs and their members as 
they execute. 

Simplify, then build up 

It sounds obvious, but if you're having trouble with a given function or feature, cut it out (either 
literally or with comments) and make sure that everything runs without it. Then replace dynamic 
data with static data (replace a database query with simple variable assignment statements). Get it 
working right under simple conditions, and add complexity in stages, testing all the way to see when 
errors appear. 

Check the obvious 

We've all heard the story about the call to tech support in which the customer complains that he 
can't see his mouse pointer move, and after lots of diagnostics it turns out that the machine isn't 
plugged in. It's probably apocryphal, but in any case make sure your that web server is work- 
ing properly on its own, and that a basic "Hello, World" script renders properly. You can also add 
p h p i n f o ( ) to the end of a simple test script to get a lot of information about your PHP interpreter's 
version and environment details. 

Speaking of version, make sure that you're not trying to do something that requires regi ster_ 
gl obal s (the infamous setting in php . i ni ) to be on. That setting is set to no by default, as of 
PHP4.2, and it's tripped up more than one programmer. 
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Document your solution 

It's extraordinarily common: You struggle with an error condition for hours (or longer) and finally 
reach a solution. At that point, don't immediately head out to celebrate. Take a minute to document 
what happened and what the solution was. That way, you'll be ready when the same problem pops 
up again — and it will. 

After fixing, retest 

It's not unusual to fix a problem and in doing so break something else. That's why it's important to 
retest your system beyond the scope of the bug you were originally after. This also points out why 
it's important to isolate bugs as much as possible — it limits the scope of retesting you have to do. 



A Menagerie of Bugs 

A number of different kinds of bugs plague programmers. Some bugs are both simple in nature and 
easily found (as is the case with syntax errors and spelling mistakes). Others are significantly more 
difficult to catch, which is why this chapter is here. 

Compile-time bugs 

PHP is a compiled language — it's compiled just before it executes, so the compilation isn't as obvi- 
ous as it is in C or Java. 

A compile-time bug is obvious to the Zend Engine, which does the compiling. The compiler will 
raise an objection, often with a line number, and you can go fix the problem. Examples of compile- 
time errors are mistyped variable names, forgotten semicolons, and mismatched parentheses. 

Runtime bugs 

A runtime bug doesn't appear until after your program is under way, and may result from some 
outside condition, such as unexpected input from a user or unanticipated behavior by a database. 
These have to be tested for, as they usually won't make themselves evident to programmers under all 
conditions. 

Logical bugs 

Logical bugs are perhaps the most difficult of all to spot and can be very difficult to fix if they result 
from an error in thinking. 

Say that you wanted to launch a space probe and have it enter orbit around Mars. However, because 
your navigation algorithm didn't allow for metric input from those pesky Europeans, your space 
probe crashed into the Martian surface. The software did exactly as it was told, which, strictly 
speaking, was to drive the rocket into Mars. That's a logical error. 
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The point: Make sure that your programs not only generate output, but generate the correct output. 
Get out the calculator and make sure that the program's results are right, or compare its results to 
values known to be good. And don't use PHP to program spacecraft, just to be safe. 

\ C' r tCj" C* „" r *' p <|iJ ^ or a g u 'de to the most common symptoms of the most common compile-time and run- 
| ^.J-^^-J-jrr time bugs> see chapter 10. 

Using Web Server Logs 

Because most PHP programs result in some sort of HTML page, which is in turn served by an HTTP 
server such as Apache or Microsoft Internet Information Server (IIS), it is possible for errors to be 
introduced by the web server software. For that reason, it is important to be familiar with the way in 
which your web server manages error reporting and logging and to know how to access and inter- 
pret the logs you need. 

Apache 

The Apache HTTP Server maintains two log files in plain-text format. They are: 

■ Ap ache/logs/access, log: Notes every HTTP request for a file, including its date, time, 
and result (success or failure, as indicated by a numeric status code). The access log also 
records the IP address from which each request came. 

■ Apache/logs/error, log: Records error conditions only. 

The Common Log Format 

By default, entries in the Apache error.log file use the standardized Common Log Format. Entries in 
this format each correspond to a single instance of request/response activity (requests and responses 
are, after all, what HTTP servers handle). For example, one line might correspond to a request for 
an HTML page (and its subsequent service by Apache). The next line might correspond to the (auto- 
matic) request for and service of a JPEG file embedded in that HTML document. 

In any case, Common Log Format entries look like this (in a single line): 

192.168.100.1 - david [ 10/Nov/2003 : 18 : 00 : 30 -1100] 
"GET /index. html HTTP/1.0" 200 6590 

The most important elements of that line are: 

■ 192.168.100.1: The IP address of the client making the HTTP request 

■ david: The username of the authenticated user making the request 

■ [10/Nov/2003:18:00:30 -1100]: The date, time, and UTC offset of the request 

■ GET: The nature of the HTTP request: GET or POST 
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■ index.html: The requested file 

■ HTTP/ 1 . 0: Version of the HTTP protocol used for the request 

■ 200: Response code describing the result of the request (more on this later in this section) 

■ 6590: The number of bytes served out in HTTP response corresponding to this request 

You'll find a more complete treatment of Apache log files, including the more obscure elements of 
the Common Log Format, at http://httpd.apache.org/docs/logs. html #errorl og. 

HTTP response codes 

Though there are many HTTP response codes (the most famous being the "404 Not Found" error), 
they exhibit a pattern that aids rapid decoding. In a nutshell: 

■ 200-series codes indicate success 

■ 300-series codes indicate a redirection 

■ 400-series codes indicate a client-side error (like a request for a nonexistent document) 

■ 500-series codes indicate a server-side error 

You'll find a full list of HTTP response codes at www .w3.org/Protocols/rfc2616/ 
rfc2616-secl0.html. 

Monitoring Apache logs with tail 

Under Unix (including Linux), you usually have access to the GNU text utility suite. When it's time 
to monitor log files, one of the most useful of these tools is tail. 

In its default behavior, tail will return the last (that is, most recent) 10 lines of a specified file. You 
can use it like this: 

tai 1 access . 1 og 

and get 10 lines of Common Log Format output (assuming that 10 loggable events have taken place). 

More usefully, though, you can use tail in its follow (- - follow) mode. In follow mode, tail returns 
the 10 newest lines of a specified file, then goes into an infinite loop in which it watches for changes 
in the file and displays them when they happen. It's a simple way to monitor log files, and lots of 
administrators dedicate several terminals to the purpose of running tail - - f sessions on various log 
files. The syntax is simple: 

tail - -f ol 1 ow=name --retry error.log 

That results in a constantly updated display of the contents of error.log. By specifying 

- -f ol 1 ow=name and - - retry, the command guarantees that tail watches the file itself, not the file 

descriptor. 



515 



Part III 



More PHP 



IIS 

The Microsoft HTTP server handles logging differently. Rather than logging to a file, IIS records its 
status and error-reporting information so that it is available for examination in the Event Viewer, 
which is one of the Administrative Tools on a Windows 2000 or XP system. 

You'll find IIS errors in the System Log portion of the Event Viewer window, with a source name of 
W3SVC. 

Microsoft offers advice on troubleshooting IIS errors at http : //technet .mi crosoft . com/ 
en-us/library/cc739055.aspx?ppud=4. 



PHP Error Reporting and Logging 

PHP can itself be a tremendous help in spotting errors. Straight out of the box, PHP will report error 
messages with output — right into the browser window, complete with line numbers. This is as far 
as most people get with PHP's debugging aids, but it's important to know about the details of config- 
uring error-reporting behavior in order to get the most out of it. 

While PHP will show you the line number on which it has detected an error, you have to be aware 
that that is not always the line to which you should go in order to make a repair. A forgotten closing 
quotation mark or neglected semicolon sometimes is not picked up by the interpreter until several 
lines later, so you should be prepared to go back a bit to look for syntax errors of that kind. 

Error reporting 

When the PHP interpreter places an error message in a program's output (most often resulting in the 
error message being displayed in a browser window), it's engaging in error reporting. Error reporting 
is a useful diagnostic tool that's turned on by default but that should be disabled on any PHP inter- 
preter associated with a production server. 

Error reporting is turned on and off in p h p . i n i . The key value isdisplay_errors.If you want 
errors to be rendered as part of your output, this line should appear in php . i ni : 

di spl ay_errors=On 

If you do not want errors to be displayed (and you shouldn't want them displayed on any publicly 
accessible machine), the line should read like this: 

di spl ay_errors=Of f 

If left on in a production server environment, error reporting can result in important details of your 
software being inadvertently displayed to users. For example, an unexpected condition could cause 
the name of a variable or a database table to appear in an unsecured browser window. An attacker 
could use this information to exploit the production server. Figure 31-1 shows an error reported as 
part of the regular output to a browser window. 
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FIGURE 31-1 



Error reporting in browser output 
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Error logging 

Similar in function to error reporting, error logging causes error events to be recorded to a text file, 
rather than to the screen. It's a more secure option, and because log files should be kept in a directory 
with limited access, it's the error-recording technique that's preferred for production HTTP servers. 

As is the case with error reporting, error logging is turned on and off in p h p . i n i . To turn it on, use 
this option: 

1 og_errors=0n 
Alternately, use this: 

1 og_errors=0f f 
By default, error logging is disabled in php . i ni . 
I p'rj r J'""'-' "rj. rr For more detail on error reporting and logging, see Chapter 30. 

Choosing which errors to report or log 

Whether you choose to use error reporting (on screen) or error logging (to a file), you can specify 
which errors are considered serious enough to record. In php . i ni , the error_ reporting value 
defines your logging preference. By default, error_reporti ng is set like this: 

error_reporti ng=E_ALL & ~E_N0T ICE 

That setting specifies that all errors and warnings are to be reported (a fact denoted by E_A L L), and 
(&) that runtime notices are not to be reported (denoted by ~E_N0TICE — the ~ indicates NOT). Other 
possible values are included and documented in the numerous comment lines of p h p . i n i itself. 

The level of reporting defined by error_ reporting affects the behavior of error logging (as 
enabled by 1 og_errors=0n) and error reporting (as enabled by di spl ay_errors=On) or both 
simultaneously if both are enabled. 
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Error-Reporting Functions 

PHP, benevolent language that it is, comes equipped with a variety of functions programmers can 
use to help locate problems and generally report on aspects of their programs' status. These range 
from ordinary output-generating statements — pri nt ( ), echo, and the like — used in contexts 
that reveal details of variable values, to specialized functions that write to operating systems' logging 
mechanisms. 

This section introduces some PHP functions you can use to spot problems and report on your pro- 
grams' condition. 

Diagnostic print statements 

The simplest troubleshooting technique involves placing echo and print statements in your code 
at key locations, so that the output contains information about the progress of execution through 
various functions and the values of key variables at different points. This is sort of a poor man's 
debugger — you can trace variables during execution and see if (and if so, when) they change to 
some unexpected value. 

Here's a simple program that uses echo statements for tracing purposes: 
<html > 
<head> 

<title>Test</title> 
</head> 

<?php 

function i nnerFuncti on ( $val ue ) ( 

echo "<BR>In i nnerFuncti on ( ) now..."; 
SreturnValue = lvalue . " things<BR>"; 
echo ' <BR>$returnVal ue = '; 
echo SreturnValue; 
return SreturnValue; 

} 

function outerFuncti on ( ) ( 

echo " < B R> I n outerFuncti on ( ) now..."; 
SreturnVal ue = "many" ; 
echo ' <BR>$returnVal ue = '; 
echo SreturnValue; 

return innerFunction($returnValue); 

} 
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echo "<P>The time has come, the Walrus said, to talk of "; 
echo outerFunctionO . 

?> 

</html > 

Using var_dump() 

The usual printing functions are handy, but more specialized ones can prove more useful for debug- 
ging purposes. 

Chief among these is va r_dump ( ) , an extraordinarily clever function that, among other things, will 
automatically render the contents of an array in a way that's comprehensible to a human reader. 

Recall that this code: 

SstateCaps = 

array( 'New South Wales' => 'Sydney', 

'Victoria' => 'Melbourne', 

'South Australia' => 'Adelaide'); 
echo SstateCaps; 

will result in some pretty useless output. It will say simply: 
Array 

Not too handy. In contrast, the same array definition, followed by this line: 

var_dump( SstateCaps) ; 

results in much more useful output: 

array(3) ( [u"New South Wales"]=> unicode(6) "Sydney" [ u " Vi ctor i a " ]=> 
unicode(9) "Melbourne" [u"South Austral i a " ]=> unicode(8) "Adelaide" ) 

It's immediately obvious to the person doing the debugging what the contents (keys and values) of 
the array are. 

Using syslogO 

PHP provides a function, s y s 1 o g ( ) , with which you can write directly into the log of the operating 
system running your PHP environment. It's a handy function, useful if you want to log all system 
problems to a standard location or if you want to alert a system administrator who might not be 
directly involved in PHP development. 

Simply put, sy s 1 og ( ) allows you to specify the degree of severity associated with the event to 
be logged and to specify a message describing it. Those values are then written out as an aid to 
diagnostics. 
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This code illustrates all possible syslogO severity options: 
<?php 

SlogOptions =array( L0G_DEBUG, 
L0G_INF0, 
L0G_N0TICE, 
L0G_WARN I NG , 
L0G_ERR, 
L0G_CRIT, 
L0G_ALERT , 
L0G_EMERG ) ; 

$excl amati ons = array (' Look! ' , 

' Ta ke note ! ' , 
'Hey! ' , 
'Uh-oh! 1 , 
' Oops ! ' , 
'Oh No! ' , 
' Look out ! ' , 
'AIYEEEEEE! ' ) ; 

foreach (SlogOptions as $key => lvalue) { 

syslog($value, $exclamations[$key]); 

) 

?> 

That code results in eight errors being written to the system log. 

In a Unix system, PHP s y s 1 o g ( ) is functionally the same as syslogO) — refer to its man page 
(man 3 syslog) — and on a Microsoft Windows system, PHP sy s 1 og ( ) writes to the Event Log 
(specifically, to its Application Log portion). 

The error-defining codes, in order of increasing severity, are: 

■ L0G_DEBUG 

■ L0G_INF0 

■ L0G„N0TICE 

■ L0G_WARN I NG 

■ LOG^ERR 

■ L0G_CRIT 

■ L0G_ALERT 

■ L0G_EMERG 
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In Microsoft Windows, the first three of those (LOG_DEBUG through LOG_NOTICE) are consid- 
ered informational; the fourth and fifth are considered warnings, and the final three are noted in the 
Event Viewer as Alerts. All of them are shown with a source value of c - c 1 i e n t , which corresponds 
to an ancillary process of the Apache server. 

The Event Viewer shown in Figure 31-2 reflects the results of the preceding listing. 



FIGURE 31-2 



Errors at various severity levels 
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Logging to a custom location 

Under Linux, you can use this procedure to write log messages to a file of your choosing. Modify 
your /etc/sysl og . conf file to include this line: 

1 ocal 0 . debug /va r/1 og/php . 1 og 
Then restart the syslog daemon: 

/etc/ i ni t . d/sysl og restart 
With that done, you can refer to L0G_L0CAL0 as part of an openl og ( ) call, as is done here: 

<?php 

def i ne_sysl og_va ri abl es ( ) ; 

openl og( "CustomLog" , L0G_PID, L0G_L0CAL0); 

$errorMessage = "Aiyeee! Dying now."; 

sysl og( L0G_EMERG, $error Message); 

cl osel og ( ) ; 

?> 

The L0G_P I D argument that supplements open 1 og ( ) states that the process ID of the offending 
thread should be recorded in the log file with the other details. 
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Using error_log() 

You can use error_log( ) to send an error message almost anywhere , including to an electronic 
mail address. It's an easy and convenient way to report on unexpected conditions that crop up in 
your PHP software, yet few developers bother to use it. 

The basic syntax for e r r o r_l o g ( ) is: 

error_l og(message , type [.destination]) 

In that syntax, type has one of four possible values: 

0 : The message is handled according to the setting of e r r o r_l o g in p h p . i n i . 

1 : The message is sent by SMTP electronic mail to the address specified by the destination 
parameter. 

2: The message is referred to a remote debugger. 

3: The message is added to the end of the file specified by the destination parameter. 
The following code shows several possible uses for e r r o r_l o g ( ) : 

<?php 

// Writes message as specified by error_Jog in php.ini. 
error 1 og( "Goodness me!", 0); 

// Writes message to e-mail address. 

error_l og( "Thi s is not spam.", I, "webmaster@wiley.com"); 

// Writes message to a remote debugger: 
error_l og( "Probl em! " , 3); 

// Writes message to a file: 

error_l og( "Save me!", 4, "/I og/php. 1 og" ) ; 

?> 

In p h p . i n i , error_log is normally not set to anything — it's commented out by default. If you want to 
use the 0 option to do anything, you'll have to modify the error_l og setting to something like this: 

error_log = syslog 

which causes er ror_l og ( ) to be the equivalent of sy si og ( 3 ) on Linux (and thus also the PHP 
sy s 1 og ( ) function) and to write events to the Event Viewer under Microsoft Windows. Alternately, 
the error_l og value can equal a filename: 

error_log = c:\logs\php.log 
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Summary 

This chapter attempted to show you where bugs come from and how to catch them when they find 
their way into your PHP programs. You saw that there are a number of resources available to you 
as you attempt to track down problems — many of them native to the PHP language or otherwise 
freely available. 

First among your bug-catching tools is the bug-reporting capability of PHP itself. If you configure 
p h p . i n i correctly — and this chapter showed you how — you can get precise reports of the line 
numbers on which the interpreter is running into trouble. Depending on your security require- 
ments, you can have the troubleshooting information conveniently displayed with the rest of the 
output (typically in the browser window), recorded in a log file, or both. You also can keep an eye 
on the HTTP logs maintained by your web server. These will help you monitor GET request data and 
spot requests for nonexistent files. 

Additionally, you should use PHP language constructs that make your programs more self-diagnos- 
tic and troubleshooter- friendly. Functions like open 1 og ( ) and sy s 1 og ( ) will record event infor- 
mation when problems occur and can really help with tracking down problems. In an even simpler 
strategy, you can use carefully placed p r i n t ( ) and (especially) p r i n t_r ( ) statements to reveal 
what's going on in your code as it executes. 

Troubleshooting PHP is not everyone's favorite activity, but with the right tools and (more impor- 
tant) the correct attitude, it can be fun. 
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This chapter is about the major points of PHP style and how it can 
enhance the functionality, maintainability, and attractiveness of 
your code. This discussion is intended to help new PHP developers 
make the main stylistic decisions, most of which are common to all pro- 
gramming languages. 

We also hope this chapter may help new PHPers decipher other people's 
code. It can be very alarming to someone just learning scripting to read 
three different tutorials, which appear totally incongruent but lack any 
explanation of the discrepancies. The information in this chapter will help 
you tease out the functionally important bits of code from the mere stylistic 
quirks and thus gain a better understanding of what you're seeing. 



IN THIS CHAPTER 



How to earn style points 
Commenting code 
Writing maintainable PHP code 
Mixing HTML and PHP 
Separating function from design 



The Uses of Style 



The primary goal of a program is, of course, functionality. After all, if your 
PHP script chokes, who's even going to care how good it looks? Error mes- 
sages are never all that stylin'. But there is a vast difference between simply 
whipping up something that will work and writing well-formed code that 
can be clearly understood by others. 

PHP programmers confront all the same style issues that other program- 
mers do, including: 

■ Readability: Sure, you understood it when you wrote it, but what 
about the next person who reads it? What if the next person is you? 

■ Maintainability: What happens when your health-advice site finally 
makes that conversion from Fahrenheit to Celsius? (A wrong answer: 
Replacing 790 occurrences of the string 98 . 6 in your source code.) 
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■ Robustness: Your web site works fine when it's getting the inputs you expect. What about 
when it gets the inputs you don't expect? 

■ Conciseness and efficiency: Fast code is better than slow code, and (others things equal) 
code using fewer keystrokes is better than code with more keystrokes (but other things are 
almost never equal). 

This chapter will give a quick overview of some strategies for achieving these goals in PHP, before 
moving on to some code organization issues that are unique to PHP. 



Readability 

Before a PHP script can aspire to be maintainable or elegant, it has to be human-readable. The 
human eye likes clear patterns, logical organization, and meaningful repetition. It also helps to have 
the most significant word or character at the beginning of a line, instead of buried in the middle. 

If you develop HTML mostly through use of a WYSIWYG tool, your notions of legibility may be very 
odd indeed. These programs are notorious for writing badly structured graphics-oriented HTML, 
filled with invisible GIFs and absolute sizing and other little horrors. 

Trying to add PHP directly to HTML files like this is an exercise in frustration, like trying to dance with 
someone who has no rhythm. If you insist on doing so, remember: It's not PHP's fault, so please direct 
your abuse to the other vendor. However, in lieu of yet another moralistic Unix-centric anti-WYSIWYG 
lecture, we'll now try to make a concrete suggestion or two for those who can't totally avoid such tools. 

Probably the single most effective step you can take to increase legibility is to run all machine- 
produced HTML through a utility that will make it more human-readable. It doesn't take very 
long at all and will improve matters substantially. A good one is HTML Ti dy, freely available from 
tidy.sourceforge.net. 

This utility will also clean up common errors in your HTML source, such as missing end tags. 
Furthermore, it has some (admittedly limited at this point) capability to cope with PHP, if you've 
used the standard < ? p h p ... ? > tags — so you can also try cleaning up those "I'm in such a hurry, 
so just this once I'll save a Microsoft Office document in HTML format and then stick in a couple of 
PHP tags' situations." 

A somewhat more labor-intensive approach that gives you finer control is to run the code through an 
HTML validator. This is a utility (many are web -delivered) that lists all the specific points at which 
a page is not in compliance with HTML standards. However, unlike HTM L Ti dy , it does not actually 
rewrite the source code; you can choose to make changes on a point-by-point basis. 

Comments 

Putting comments in code is just like flossing your teeth: important for health and hygiene, the object 
of many good intentions, all too often skipped "just this once," and long regretted later if undone. 
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The problem is that there's no immediate glory to be had from commenting — all the benefits are 
longer term and diffuse. Let's face it: You rarely hear hackers oohing and aahing over the beautiful 
commenting of the guy in the next cubicle, and few web sites' go-live dates are allowed to slip so 
that the programmers can put the finishing touches on their comments. Commenting comes into its 
own later, when your team leader quits (in the middle of a major site redesign) to join a neo-Luddite 
community, and the rest of you are sitting around scratching your heads and thinking "Huh?" in 
unison, as you desperately try to write up some documentation in time for the scheduled release. So 
what kinds of things should you comment? We feel you must explain: 

■ Anything with future "what the heck was I thinking?" potential (usually due to extreme 
cleverness or extreme ugliness) 

■ Anything you suspect might be a temporary expedient 

■ Anything that will lead to dire consequences if tampered with by someone less experienced. 

Things that ideally should be noted include: 

■ The date the file was originally created and the name of the creator 

■ The date the file was most recently altered, the name of the alterer, and possibly an expla- 
nation of the rationale behind the alteration 

■ Any other files or programs that depend on the existence of this file 

■ The intended purpose of the file and of its constituent parts 

■ Things you might want to mention in documentation you're planning to write later 

■ The reason you want to save something that isn't being used (alternate versions, archive 
copies, and so on), conditions under which it might become okay to throw it away, or your 
plans for what to do with it 



Obviously, you're in a better position than we to decide whether these items are strictly necessary. If 
you're using PHP for a very small, purely personal site, maybe commenting would be superfluous, 
but the bigger and more complex the site, the more you need to annotate your own work. In theory, 
it's possible to overcomment, but, in practice, few programmers are guilty of this offense. 

As we detailed in Chapter 4, there are several styles of PHP comments. Remember that 
none of these will be visible from the client machine, even when HTML source is viewed. 
If you want client-readable hidden text, you must use HTML comments. 



PHPDoc 

For very large and complex programs, code-embedded comments are not sufficient. You want sepa- 
rate documentation that someone can read without delving into the code itself. The problem with 
documentation like this, however, is not just how anyone gets the time to write it (since that is often 
low priority), but how it stays in sync with the code (which is even lower priority). When starting a 
new day job, we have more than once confronted a very common choice: Should we get to know the 
code by reading the current code itself or by consulting some very nicely written documentation of 
the code as it was two years ago? 
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One approach, used with some languages, is to employ a tool that produces documentation by 
extracting specially formatted, embedded comments from the code. For example, if you have fol- 
lowed a given commenting convention, you can point the j a v a d o c tool at your Java code and it will 
extract class and method comments into a set of HTML pages documenting the API. This is not a 
magic solution for the problem of keeping docs in sync with code. (It will break down, for example, 
if people begin writing new methods by copying old methods, and leaving the original comments in 
place.) But at least developers have to write only one description of a given method rather than two. 

There is an analogous phpdoc tool that uses PHP (naturally) to scan PHP code for special com- 
ments, producing HTML output. If you are doing a large-team project, though, especially one 
making heavy use of object-oriented PHP, you might find phpdoc to be helpful. For more on 
phpdoc, see www .phpdoc.org. 



File and variable names 

Some people act like thinking up variable names is equivalent to being forced to write an epic 
poem — they go into a kind of writer's block and become creatively incapacitated. For instance, we 
once had an intern who was apparently unable to think up a single name or even a halfway decent 
scheme for doing so. This person's habit was to name every new file according to simple sequential 
order: f i 1 el6 . html , f i 1 el7 . html , f i 1 el8 . html , and so forth. Each variable on a web page was 
called varl, var2, and so on. This story would be a lot funnier if it had happened to someone else. 

Because PHP generally requires a lot more variables than HTML, you need a robust naming scheme 
for all occasions. The following sections include a few tips. 

Long versus short 

Longer is generally better because it's more informative. You can break up long names with under- 
scores or capitalization if necessary. 

Even though most filesystems technically allow for long filenames, the results are not pretty when 
viewed as icons — so GUI users may be consciously or unconsciously averse to using long file- 
names. Icon labels are usually quite short and, thus, naturally lend themselves to very concise file- 
names. Try giving a file a long, complex name (like PoachedPeachesRecipe.php) and putting it 
on your desktop — the result is just viscerally displeasing. 

~~~T^"V' : ?H : Most GUI-oriented filesystems allow and even encourage filenames with spaces in them 
UmAmm^K (f or example, My Document . doc). Unix systems do in theory, but in practice it's not 
such a good idea. PHP will try to cope gracefully with such filenames, but it may not be able to do so in 
all situations. 

One benefit of using PHP for dynamic content generation is that you can use shorter filenames that 
will be expanded and differentiated by GET-style query strings. For example, a static site might use 
this style of filename to uniquely identify each page: 

FeatureHitchcockBirds.html 
MiniseriesIrvinSpy.html 
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A dynamic site, on the other hand might identify the same pages like this: 

feature . php? I D=l 
mi ni sen' es . p h p ? I D=2 

In this situation, you can have the hest of both worlds: short filename plus unique identifier. (The 
only downside of this is that some search engines still discriminate against pages with dynamic 
arguments, under the theory that the contents are likely to change with every page view and, there- 
fore, won't be worth indexing.) 

PHP sets no particular limit on the length of variable names. So feel free to invent lengthy but infor- 
mative variables like SAddressOfClientCompanylnSasketchewan. Hey, it's your script — we're 
just living in it. You only need to be careful if you plan to use a lot of long-name variables as part of 
a GET-method form. 

Underscores versus camelcaps 

There are two typical ways to break up long variable and file names in Unix. Underscores look like this: 

$name_of_f avori te_beer 
whereas camelcaps look like this, with the internal capital letters giving the name a humped profile: 

$NameOfFavoriteBeer 

It's a purely personal preference, which style you use (unless you have agreed on a particular style 
with your colleagues). PHP itself uses underscores ( $ PH P_S E L F), but this usage by PHP could be 
construed as an argument in favor of either scheme for PHP programmers. Just remember you can't 
use dashes and should be careful with dots. 



Unix filenames are case sensitive all the time. Filenames in other OSes, such as 
Windows, are not case sensitive. If you might be in a position to move PHP files 



between OSes, be careful. 

The main thing to strive for here is consistency. It's frustrating to spend a lot of time trying to figure 
out why $My_N umber was never assigned, only to find out that it's because you called it $ My Number 
when you assigned it. 

Reassigning variables 

Situations arise in which you deliberately want to keep using the same variable name over and over 
rather than coming up with new names. This happens when you need to be certain only one vari- 
able of a particular type will be valid at any given time. For instance, you might want to be sure 
there can be no confusion about which of two database queries will be used for an operation, which 
you can ensure by using the same name for both (for example, $ query). PHP will overwrite the for- 
mer with the latter, and your variable will always be minty fresh. 
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Uniformity of style 



Although we have talked in a very free-and-easy way about how all these stylistic choices are up to 
you, there are situations where it is actually good to have a consensus on what code should look like 
and then enforce that. This is particularly true when many programmers will contribute code to a 
project. The reasons that are usually advanced for a uniform style are: 

■ It makes it easier to read code from multiple programmers, because you don't have to get 
used to a new indenting or layout style every time you see new code. 

■ It makes life easier for version control software (like CVS). If I change a code file that you 
created and my editor changes the indentation, there will be a lot of apparent but spurious 
differences. 

The closest thing PHP has to a consensus style is the coding standard developed by the maintainers 
of the PEAR project. See Appendix E for a discussion of both PEAR and this coding style. 



Maintainability 



Many seasoned programming veterans, especially those who are also managers, tout the importance 
of maintainability above that of any other virtue. 

The problem is, of course, that maintainability is in direct conflict with all the other goals — espe- 
cially speed. When Internet Time gets into the ring with Hypothetical Future Code Maintenance by 
Someone Probably Not Myself, everyone knows how the story is going to end. Still, the main mental 
mantras of maintainability are worth keeping in mind: 

■ The things that are most likely to be changed should be the easiest to find. 

■ Changing those things should not have unpredictable effects. 

■ Each change should have to be made in only one place. 



Avoid magic numbers 



A magic number is a numerical value that might someday have to be changed but is buried deep in 
code, often in multiple places. Imagine, for example, these lines of code found in your bank's hypo- 
thetical PHP-based web site: 

print("The interest rate on your CD can be as high as 

5 . 5% ! <BR>" ) ; 
$sample_gains = 5000 * 1.055; 

print("After a year, a \ $ 5 000 investment could grow to 
\$$sampl e_gai ns ! <BR>" ) ; 
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Now, when times get tighter and the rate goes down to 5.0 percent, someone has to find and change 
every instance of the rate. So, someone does a text search for 5 . 5, which misses the 1.055 in the 
second line here, and now your bank is engaging in false advertising. 

For simple sites, a better alternative can be as easy as using an $ i nterest_rate variable, which is 
assigned very visibly at the top of a script — a change in rate means a change only to that assign- 
ment statement. More complex sites might produce their pages as function calls, with variables 
like $ i n teres t_r ate being passed in as an actual parameter. Finally, some sites will go so far as 
to have all their content imported from a database, so that no piece of information has to ever be 
changed directly in code. 

Functions 

Having tried to maintain a complex site using a web-scripting language that did not support func- 
tions, we can say from our own experience that functions are crucial to maintenance. The art of pro- 
cedural abstraction via functions needs a book in itself, but here's some brief advice: 

■ Always look for opportunities to bundle naked PHP code into a function, especially in 
cases where it might be reused. 

■ Try to keep function definitions short — if a definition gets too long, break it up into mul- 
tiple functions. 

■ Always load all your function definitions before any code that calls any functions. 

Include files 

One of the great benefits of dynamic web page generation over static HTML is the opportunity to 
fight redundancy. Anyone who has ever managed a static site of any size knows how much of each 
file is boilerplate — and even editing a single character on each page isn't a picnic if your site has 
200 pages. 

PHP makes it very easy to drop anything into your scripts, from one character to a whole separate 
program, by using the built-in i ncl ude or requi re functions. The syntax is simply: 

<?php i ncl ude( "f i 1 erame . ext" ) ; ?> 

You can also use a variable filename, like this: 

<?php 

$LastName = "Park" ; 
include("$LastName.inc"); 

?> 

which will result in the contents of the file P a r k . i n c being spliced in at the location of the include 
statement. 



531 




More PHP 



You can use any extension you want for the included file. Popular choices include . txt, . i nc, and 
even .html to remind yourself that the file will show up in HTML mode. 

A few things to remember: 

■ PHP will drop the entire text of the file into your PHP script in HTML mode (as explained in 
Chapter 4). If the included file is itself meant to be parsed as PHP, you must use valid PHP 
tags at the beginning and end. If any part of the file is meant to be parsed as PHP, you must 
use valid PHP tags around that section. 

■ Recall the difference between i ncl ude/requi re and 1 ncl ude_once/ requi re_once. In 
general, if what you are including or requiring is a set of function or class definitions, you 
should use the once variant. If it is straight PHP or HTML, then which variant you load 
depends on whether you would ever want that literal block to repeat in your output; if not, 
then the once version is probably still what you want. 

■ include can also be used to assemble complex web pages from text files instead of from a 
database. In some cases, this can even be faster — usually when the included data is just a 
sizable text file(s). However, after you go to the trouble to make a database connection for 
any reason, it's probably just as fast to store your big chunks of text there, too. 



Although we haven't covered PHP's object system in detail yet, it's worth noting that consistent use 
of objects can make code more maintainable, much as functions do. For example, some developers 
of database-enabled PHP sites are disciplined enough to wrap up all of their database-specific func- 
tionality in the methods of an object, so that the rest of their code doesn't even know what kind of 
database is supporting the site. In theory, then, if they decide to move from a mySQL database to an 
Oracle database, only the object-level code will have to be changed. 

CC rj P r " ^ or details on PHP's support for object-oriented programming, see Chapter 20. 



For large multiprogrammer projects in industrial settings, version control isn't "something to con- 
sider" — it's a must. Similarly, large decentralized open-source projects could not survive without 
CVS (Concurrent Versions System) or SVN (Subversion). Even if you are working by yourself or with 
one other person on a hobby project, using version control can free you to do more experimentation, 
secure in the knowledge that you can get to the older versions of your code if something goes awry. 

See www . cvshome . org for more information on CVS. SourceForge also offers free web-based CVS 
project hosting for open source projects (www .sourceforge.net). 



Object wrappers 




Consider using version control 



532 



Learning PHP Style 



Robustness 

The two commandments of robustness are: 

■ Code should detect unexpected situations and respond gracefully rather than dying. 

■ If code must die, better that it die informatively. 

Writing robust code is at first a difficult task of imagination, where the programmer tries to think 
ahead to all the things that might go wrong and to cover those cases. The ideal situation is for that 
habit of mind to become a habit of code, so that the coder has a standard set of tests that wrap 
around the standard potential problems. Although most of the robustness issues in PHP are the 
same as in any language, there are two kinds of situations to cover that are more specific to PHP: 
problems with an external service, and problems having to do with variable type. 

Unavailability of service 

PHP is in part a "glue" language, offering a single environment where a variety of different code 
libraries and external services can be invoked. Any given PHP page might open a file, connect to 
a database, query an LDAP server, send an HTTP header, or send mail via an SMTP server. The 
important habit to develop is covering cases where for some external reason a service is unavailable, 
or times out, or behaves oddly, or gets interrupted in the middle. 

Often, such services have error states that can be retrieved and printed if the only option left is to infor- 
matively die. For example, a reasonable construct for making a connection to a mySQL database is: 

$connection = my sql ^connect ( [arguments] ) or 

di e ( " Connecti on failed: $php_errormsg<BR>" ) ; 

This is preferable to the weird and unexpected errors you would see if your code went happily ahead 
assuming that it had a live database connection. An alternative that is better from a security point of 
view is: 

$connection = my sql _connect ( . . . ) or er ror_l og ( $php_er rormsg ) ; 
if ( ! $connecti on ) ( 

die( "Connection Failed"); 

} 

because this will avoid displaying interesting facts about your PHP and database configuration to 
the user's browser. 

Even better style is to use the exception-handling facility introduced in PHP5, rather than simply 
failing with d i e ( ) . Exceptions can be thrown whenever a problematic condition is encountered, 
and recovered from, at a single point in the code (if you so choose). If it is possible to recover from 
the problem, exceptions make it easy to structure your code to support that. If the script must die 
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anyway, exceptions make it easy to propagate the negative information and display it at the right 
time, rather than just aborting execution. 

i (-' jy f~j £)£}"-.]'■' ' PJ-' Exceptions and exception handling are covered in detail in Chapter 30. 

Unexpected variable types 

Although the type-looseness of PHP is for the most part a good thing, it leaves a little bit of uncer- 
tainty for the programmer about exactly what type a variable or value will turn out to be. Unless 
you come to know all the type conversion rules very well, it can be surprising to have code that 
is accustomed to strings suddenly run across a value that is a number, all because some PHP con- 
struct decided that any string composed only of numerical digits must really be a number at heart 
One interesting robustness check is to use a text editor to search your code for $ (thereby finding 
every variable) and ask yourself for each one what would happen if the type turned out to be sur- 
prisingly different. 



Efficiency and Conciseness 

Efficiency and conciseness are not the same thing. Efficient code runs using a small amount of exe- 
cution time or computer memory, while concise code accomplishes a given task in a small number 
of lines or keystrokes. In this section, we give some quick tips toward writing efficient and concise 
PHP code, along with our extremely opinionated commentary about in what senses these goals are 
worth striving for. 

Efficiency: only the algorithm matters 

There was a time when computer memory and computer cycles were so precious that it was worth a 
lot of effort to boil down your code to the smallest number of resulting machine instructions possi- 
ble. This is still true in certain areas of software development (kernel programming, graphics librar- 
ies), but for most development tasks, saving a few instructions or a few K is not worth backing off 
on any other goal. This is especially true for web scripting, where there is always going to be some 
overhead of purely Internet-related execution delay. If it takes half a second for a user to fetch your 
page, regardless of how your page is produced, then an extra five milliseconds on the server side will 
be lost in the noise. 

With that said, there's one variety of efficiency that matters and will probably always matter: the 
broad algorithm or approach that your code uses for a task. For example, if your code locates a name 
in a database by querying the database for all names and then doing a string comparison for each 
name to see if it's the one you want, you'll soon find out how much efficiency can matter. 

Efficiency optimization tips 

Here are some quick mantras to repeat as you code. 
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Don't reinvent the wheel 

It's usually a bad idea to write code that duplicates a language-level facility, unless it's for purposes of 
fun or education. For example, any programmer worth his or her salt should write sorting routines at 
some point in their education, but no programmer should have to keep writing them (unless it is actu- 
ally in their job description). Most high-level programming languages offer some kind of sorting capa- 
bility (either as part of the language or in a library), and it's very likely that the programmer who wrote 
them did a better job than you will. PHP is no exception here — the array type supports several types 
of sorting, and most of the databases supported by PHP have sorting options built into the query lan- 
guage. Either of these options will be faster and more reliable than what you get by rolling your own. 



Discover the bottleneck 

Although it's good to try to use efficient algorithms from the beginning, it's often not worth doing 
other kinds of optimization until you find out that too much of some resource is being used. At that 
point, you want to tighten things up, and you'll get the most reward for your effort if you focus on 
the piggiest parts of your code. Most code follows the 90/10 rule: 90 percent of the time is spent in 
10 percent of the code, and you want to locate that 10 percent. 

One technique that programmers often use to locate that 10 percent is called profiling. A profiler is 
a utility that tracks code as it runs, noting the time spent in every function call, and producing a 
neat summary of the results. Unfortunately, at this writing, there is no good general profiling utility 
for PHP (although you may want to look at XDEBUG with Kcachegrind). So the best bet for now is 
the poor man's profiling technique: printing the value of the function call m i c r o t i m e ( ) in various 
places in your script to see where the time is going. If the 90/10 rule is in effect, the time sink will 
usually be glaringly obvious. 



Focus on database queries 

Although we cover database efficiency in more detail in Chapter 18, you should be aware that data- 
base queries are usually the biggest time sink for PHP sites that have database backends. Especially 
if your database-enabled site doesn't do a lot of other computationally intensive work, your first sus- 
picious glance should be at the queries, and your next task should be to try to identify a query that 
is particularly time-consuming. After you've identified a guilty query, there are a host of techniques 
available to speed that query up, many of which don't have anything to do with PHP. 



C ^ J CjCf Cj^^ p p ^ or details on optimizing database-enabled PHP code, see Chapter 18. 



Focus on the innermost loop 

Let's say that you have a page with embedded looping constructs, like the following: 

for ($x = 0; $x < 100; $x++) 
{ 

do_X( ) ; 

for ($y = 0; $y < 100; $y++) 
t 

do_XY( ) ; 
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for ($z = 0; $z < 100; $z++) 

{ 

do_XYZ( ) ; 

) 

} 

! 

Unless you have a really good reason to think otherwise, your optimization focus should be on the 
function do_XY Z ( ) (which will execute 1,000,000 times) rather than on the other two functions 
(10,000 times and 100 times). 

Conciseness: the downside 

Before we get into how to write more concise code, let us say that we think conciseness is an over- 
rated virtue, for the following reasons. 

Conciseness rarely implies efficiency 

Although it's true that somewhere in the guts of the PHP engine, the characters of the code you 
write are being consumed one by one (and so, in theory, more code takes more time), in practice, 
the Zend-based parsing engine of PHP is so zippy that the number of characters just doesn't matter. 
Ditto for the time or space consumed in extra variable assignments or the overhead of extra function 
calls. 

You should generally strive to reuse code whenever possible. This means thinking through the 
design of your code and using functions where it makes sense rather than repeating code. 

Conciseness trades off with readability 

Remember that every keystroke you omit might be the keystroke that would have let someone figure 
out what the heck you were thinking when you wrote the code. For example, take a look at the fol- 
lowing admirably concise function: 

function sieve($n) ( 

for ($i = 2; $i <= sqrt($n); $i++) 

for ($j = $i, $ i nd = $i * $ j ; $ind <= $n; 
$j++, $ i nd = $i * $j) 
$ca r ray [ $ i nd] = 1; 
for ($i = $n, $ p 1 i s t = array(); $i > 1; $i--) 

if ( ! $carray[$i ] ) a rray_push ( $pl i st , $ i ) ; 
return($plist); 

} 

Obviously, this implements the Sieve of Erasthones, and $pl i st is a list of all the prime numbers 
less than $n. Obviously. 
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So why do programmers strive for conciseness? The first reason is that it saves them time (but only 
at the time of actual code writing). The second reason (and we're only half-joking) is that they're 
afraid some other programmer (probably one trained in C) will come along later, laugh at them, and 
point out that their code could have been written in only half the space. 



If you must write code that fits in less space, try some of the following techniques. 

Use return values and side effects at the same time 

It's a very common trick to exploit the fact that the value of an assignment is the value assigned, as 
in the following pseudocode: 

while ($next = GetNextOne ( ) ) 
DoSomethi ngWi th ( $next ) ; 

where GetNextOne( ) is some function that returns useful values in sequence and then returns a 
false value when it runs out of them. When a false value is returned, $next is false, and the while 
loop terminates. 

Use incrementing and assignment operators 

The incrementing operators (++ and - -) shorten statements that involve adding or subtracting one 
from a variable, and the combined assignment operators (+=, *=, . = , and so on) make certain kinds 
of assignments more concise. 



which (assuming that $ c o u n t starts as a positive integer) would call its function for the very last 
time on the value 1. 

Reuse functions 

This is one case where conciseness is good, because functions are good. If you can identify any 
stretches of code that get duplicated in your pages, try to replace each one with a call to a single 
function that packages up that code. Your code will be shorter by the amount of the duplication and 
also easier to maintain. 



Conciseness tips 




>- ™ >i. rr The incrementing operators and the arithmetic assignment operators are covered in 
Chapter 9, and the combined string assignment operator (. =) is covered in Chapter 7. 

Often these operators are used in combination with the previous trick, as in: 



while ($count--) 

DoSomethi ngWith($count) ; 
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There's nothing wrong with Boolean 

Beginning programmers often have an odd distrust of Boolean values, not realizing that they can be 
passed around as freely as any other kind of value. This leads to code that wastes a lot of space, like 
the following: 

function Di vi s i bl eByBad ( $numl , $num2) 
{ 

if ($numl % $num2 == 0) 

return(TRUE) ; 
else 

return( FALSE) ; 

} 

/ * using the function * / 
if (DivisibleByBadO, 3)) 

$di vi si bl e_resul t = TRUE; 
else 

$di vi si bl e_resul t = FALSE; 
if ( $di vi si bl e_resul t == TRUE) 

printCIt's di vi s i bl e ! <BR> " ) ; 
else 

if ($divisible„result == FALSE) 

printCIt's not di vi s i bl e ! <BR> " ) ; 

A more concise version would look like: 

function Di vi si bl eByBetter( $numl , $num2) 
{ 

return ($numl % $num2 == 0); 

} 

/ * using the function * / 
if (DivisibleByBetter(9,3) ) 

printCIt's di vi s i bl e ! <BR> " ) ; 
else 

printCIt's not divisible!<BR>"); 
You could obviously take this one step further and get rid of the function itself, like this: 

if (9 % 3 == 0) 

printCIt's di vi s i bl e ! <BR> " ) ; 
else 

printCIt's not divisible!<BR>"); 

But (once again) Functions Are Good — an explanatory function name is a little piece of documenta- 
tion in itself, and any function you write gives you a chance to reuse it later, which, in turn, makes 
your code more maintainable. 
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Use short-circuiting Boolean expressions 

Certain kinds of Boolean tests aren't safe to apply until you've done other tests. It's tempting to deal 
with this hy insulating the problematic tests with i f constructs. For example, imagine that you 
want to print the ratio of two variables that are bound to integers, but only if they are bound to inte- 
gers and only if the ratio is greater than two. Also, you want to avoid a division-by-zero warning. 
You might overcautiously write: 

if (IsSet($x)) 
{ 

if (IsSet($y)) 
{ 

if ( Is_Integer( $x) ) 

{ 

if ( I s_Integer ( $y ) ) 
{ 

if ($y != 0) 
I 

if ($x / $y > 2) 

print("Ratio is " . ($x / $y)); 

) 

) 

} 

} 

} 

You can be equally overcautious and still type a little less, as in: 

if (IsSet($x) && IsSet($y) && Is_Integer( $x) && 
Is_Integer($y) && $y != 0 && $x / $y > 2) 
print ("Ratio is " . ($x / $y)); 

The tests will be applied in left-to-right order, and if any test fails, the tests to the right of it will not 
be evaluated. 



HTML Mode or PHP Mode? 

There's a spectrum of ways to combine PHP and HTML, functionally all pretty much the same. Your 
choice will depend on extrinsic factors such as your particular team's workflow. 

The easiest way to demonstrate all this is to simply write the same script in minimal PHP, maximal 
PHP, and medium PHP styles. We will also include a version using the heredoc construct (discussed 
in Chapter 7). Remember, these are equally correct and return much the same result. The stylis- 
tic decision is just a matter of preference and consistency, and (sometimes) slight differences in 
functionality. 
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Minimal PHP 

The code in Listing 32-1 shows a simple self-submitting form, which returns some simple information 
about days of the week. First, it tells you what day it is today and then gives you a chance to ask it what 
day it will be in a few days (using a form with a pull-down list). The typical text output looks like this: 

4 days from this moment it will be Thursday 
Today is Sunday 

Please choose a number of days, and we'll tell you what day it will be 
that many days from now 

It is written using a minimal PHP style, meaning simply that, as much as possible, the code is pure 
HTML, dropping into PHP mode only when dynamic data must be displayed (such as the current 
day of the week or an answer that depends on submitted data). 



LISTING 32-1 



calendar.php - An example with minimal PHP 

<HTMLXHEAD TITLE="Cal endar Server "></HEADXBODY> 
<H2>Welcome to the Calendar Server</H2> 

<?php if (IsSet($_POST['DAYS'])) { ?> 
<P> <?php echo $_P0ST[' DAYS' ];?> 
days from this moment it will be 
<?php $date = getdate ( ti me ( ) + 

($_P0ST['DAYS'] * 86400)); 
echo ( $date[ 'weekday ']) ; 

)?> 

<P>Today is <?php $date = getdateO; 

echo($date[ 'weekday ']) ; ?> 
<P>Please choose a number of days, and we'll 
tell you what day it will be that many days from now: 

<F0RM METH0D=P0ST ACTI0N="cal endar . php" > 

<SELECT NAME=DAYS> 
<0PTI0N VALUE=1>K0PTI0N VALU E=2>2<0PTI ON VALUE=3>3 
<0PTI0N VALUE=4>4<0PTI0N VALU E=5>5<0PTI ON VALUE=6>6 

</SELECT> 

<INPUT TYPE=SUBMIT NAME=SUBMIT V A LU E=SU BM I T> 
</F0RM> 

</B0DYX/HTML> 



This code takes the minimal style to an extreme — note the funny business with the i f statement 
near the top, where some straight HTML text (day s from this moment) is included conditionally, 
based on the results of the PHP statement that precedes it. 
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As we have said, this is a matter of taste, but we don't like this version very much. It's a bit hard to 
see exactly what is being produced by the PHP snippets that are spliced into the page. 

Maximal PHP 

At the opposite extreme, consider the code in Listing 32-2. This version is in PHP mode all the time 
and simply prints all the HTML it needs to as it goes. 



LISTING 32-2 



calendar.php An example with maximum PHP 

<?php 

pri nt ( "<HTMLXHEAD TITLE=\"Cal endar Server\"X/HEADXBODY>") ; 
pri nt ( "<H2>Wel come to the Calendar Server</H2>" ) ; 

if (IsSet($_POST['DAYS'])) ( 
print("<P>" .$„P0ST[' DAYS'] . 

" days from this moment it will be "); 
$date = getdate ( ti me ( ) + 

($_P0ST['DAYS'] * 86400)); 
print ( $date[ ' weekday '] ) ; 

1 

$date = getdate ( ) ; 

$day_of_week = $date [' weekday '] ; 

pri nt ( " <P>Today is $day_of_week" ) ; 

pri nt ( "<P>P1 ease choose a number of days, and we'll 

tell you what day it will be that many days from now:"); 

print("<F0RM METH0D=P0ST ACTIONX " cal enda r . php\ " >"); 
print("<SELECT NAME=DAYS>" ) ; 
for ($i = 1; $i < 7; $i++) ( 
printC "<0PTI0N V A LU E= $ i > $ i " ) ; 

1 

print("</SELECT>"); 

print("<INPUT TY PE=SUBM IT NAME=SUBMIT VALUE=SUBMIT>" ) ; 
print("</F0RMX/B0DYX/HTML>") ; 

?> 



Another term for maximal PHP might be CGI-style, because we are not taking advantage of the 
HTML-embeddedness of PHP at all, and might as well be writing a CGI script in C or Perl (and who 
wants to do that?). Again, a matter of taste, but it's a little bit hard to visualize the structure of the 
HTML page that will result from running this. 
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Medium PHP 

An intermediate version that better exploits functions is shown in Listing 32-3. It spends about half its 
text in PHP mode, defining functions, before dropping back to a minimal style for the rest of the script. 



LISTING 32-3 



calendar.php - An example with medium PHP 

<?php 

function maybe_pri nt„answer„date () ( 
$seconds_in_day = 60 * 60 * 24; 
if (IsSet($_POST['DAYS'])) { 
print("<P>" .$_P0ST[' DAYS'] . 

" days from this moment it will be "); 
$date = getdate ( ti me ( ) + 

($_P0ST['DAYS'] * $seconds_in_day) ) ; 
print($date[ 'weekday ' ] ) ; 

) 

} 

function pri nt_day_opti ons () { 
for ($i = 1; $i < 7; $i++) 1 
print( "<0PTI0N VALUE=$i >$i " ) ; 

) 

} 

function get_day_of_week( $t i me ) { 
$date = getdate($time); 
return ( $date[ ' weekday ' ] ) ; 

} 

?> 

<HTMLXHEAD TITLE="Cal endar Server "></HEADXB0DY> 

<H2>Welcome to the Calendar Server</H2> 

<?php maybe_pri nt_answer_date( ) ; ?> 

<P>Today is <?php echo get_day_of_week(time( ) ) ; ?> 

<P>Please choose a number of days, and we'll 

tell you what day it will be that many days from now: 

<F0RM METH0D=P0ST ACTI0N="cal endar . php"> 
<SELECT NAME=DAYS> 

<?php pri nt_day_opti ons ( ) ; ?> 
</SELECT> 

<INPUT TYPE=SUBMIT NAME=SUBMIT V A LU E=SU BM I T> 
</F0RM> 

</BODYX/HTML> 



542 



Learning PHP Style 



Maybe the medium style is a little bit more verbose, but to our eyes, it's also a little easier to read and 
modify than the minimal and maximal styles. 

The heredoc style 

Listing 32-4 shows a rewrite of the medium style, using the heredoc syntax for constructing strings. 



LISTING 32-4 



Heredoc style 

<?php 

function answer_stri ng ($days) { 
$seconds_i n_day = 60 * 60 * 24; 
$return_stri ng = " " ; 
$day_string = 

day_of_week_stri ng ( t i me ( ) + $days * 
$seconds_i n_day ) ; 

$return_stri ng .= 
$_P0ST[' DAYS'] . 

" days fnom this moment it will be " . 
$day_stni ng ; 
return ( $return_stri ng ) ; 

1 

function day_of_week_st r i ng ( $ti me ) ( 
$date = getdate ( $t i me ) ; 
return ($date[ ' weekday ']) ; 

} 

function cal endar_form„stri ng () ( 
$opti on_stri ng = " " ; 
for ($i =1; $i < 7; $i++) { 

$option_string .= "<0PTI0N VALUE=$i >$i " ; 

1 

$self_string = "thisfile.php"; $return_stri ng=<<<E0T 
<F0RM METH0D=P0ST ACTI0N=" $sel f_stri ng" > 
<S ELECT NAME=DAYS>$opti on_stri ng</SELECT> 
<I NPUT TY P E=SUBM IT NAME=SUBMIT VALUE=SUBMIT> 
</F0RM> 
EOT; 

return ( $return_stri ng ) ; 

1 

// set up string variables 
$answer_string = I sSet ( $_P0ST[ ' DAYS ' ] ) ? 
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answer_string($_POST['DAYS']) : 

$day_of_week = day_of_week_st ri ng ( t i me ( ) ) ; 
$f orm_stri ng = cal enda r_f orm_stri ng ( ) ; 

// set up page string 
$page_stri ng=<<<E0T 

<HTMLXHEAD TITLE="Cal endar Server "></HEADXBODY> 
<H2>Welcome to the Calendar Server</H2> 
<P>$answer_stri ng 
<P>Today is $day_of_week 

<P>Please choose a number of days, and we'll 

tell you what day it will be that many days from now: 

$f orm_stri ng 

</BODYX/HTML> 

EOT; 

echo ( $page_st r i ng ) ; 
?> 



Tim Perdue of SourceForge has made the stylistic argument that it's a bad idea for functions to 
print output to the browser. The heredoc example follows this advice and uses functions only for 
calculations and for building strings that are returned. The heredoc construct is used twice, first to 
build a string corresponding to the form that will be displayed and then (using the form string) to 
build the string corresponding to the entire page. The last act of the script is to echo out the string 
it has constructed. 

This is the most verbose of the four, but the heredoc syntax has the advantage (over the maximal 
style) that we never have to do any escaping of quotes. Another advantage (over the minimal style) is 
that we can simply include variables in our page template without dropping out of HTML mode to 
do so. It is probably the best version of the four at separating logic from page structure. 



Separating Code from Design 

Many of the topics in this chapter have obvious implications for the separation of code and design. 
Here are a few additional techniques we should mention. 

Functions 

As you can see from our Medium PHP example in Listing 32-3, using self-defined functions can be a 
very flexible and powerful formatting tool, as well as one of the things that make PHP better than a 
tag-based scripting language. 
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Cascading style sheets in PHP 

As you doubtless already know, there are four generally accepted ways to apply styles to your web pages: 

■ By applying CSS formatting to individual tags. 

■ By using <STY LE> tags (optionally inside a pair of HTML comment tags). 

■ By using < LIN K> tags. 

■ By using ©import. 



j j F In this book, we've typically used the <STY LE> tag in each code sample rather than an 
~" - ■ external style sheet. This is solely so you, Dear Reader, can see the style declarations we 
used to get the results we display in the figures. There is absolutely no PHP-intrinsic reason for this usage. 

In PHP, you could also use the include function to apply styles in a nonstandard way, although it's 
not clear how much of a gain this would be. For instance, you could i n c 1 ude a text file containing 
everything between the <STY LE> tags, instead of linking to an external style sheet. 

We should also mention the anti-style sheet, a practice almost as long-deprecated as it is common: 
using outdated HTML tags such as FONT, BGCOLOR, and ALI NK. Although you shouldn't do it at all, 
PHP can help you do it more efficiently if for some reason you must. This usage, for instance: 

<F0NT FACE="<?php i ncl ude ( "f ontl i st . txt " ) ; ?>" SIZE=+2> 

would at least allow the poor, overworked web developer to change the fonts throughout the whole 
site with a single edit of the text file. Not that we can condone this kind of thing! Only slightly less 
kludgy would be this alternative: 

<P STYLE="font-fami ly : <?php i ncl ude( "f ontl i st.txt" ) ; ?>">Text here</P> 



Templates and page consistency 

As you can now imagine, PHP allows a wide variety of approaches to site design, which you can fit 
to your particular style and the organization of the people who work on the site. If your techies can't 
talk to your artists, you may want to set things up so that they never touch the same files; if you're a 
tech artist, you may express yourself by the very intermingling of code and graphics. If your site has 
a large number of pages or is very content rich, you may find (as we have) that it's helpful to choose 
a particular kind of file organization or template, and stick to it across the site. One simplified 
example follows, which is similar to templates we have used on www .my steryguide.com and 
www .sciencebookguide.com. 

<?php 

/* load general functions */ 

include("general-functions.inc"); 

/* load functions specific to this page */ 
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include("renaissance-functions.inc"); 

/ * page-wide variables * / 

$PageTitle = "Painters of the Renaissance"; 

$db_connecti on = ma ke_database_connect i on ( ) ; 

?> 

<HTML> 
<HEAD> 
<TITLE> 

<?php pri nt ( " $ PageTi tl e " ) ; ?> 
</TITLE> 
</HEAD> 
<B0DY> 
<H3> 

<?php pri nt( "$PageTi tl e" ) ; ?> 
</H3> 
<TABLE> 
<TRXTD> 

<?php pri nt_l eft_si de( $db_connecti on ) ; ?> 
</TDXTD> 

<?php pri nt_ri ght_s i de ( $db_connect i on ) ; ?> 
</TDX/TR> 
</TABLE> 

<?php pri nt_footer( $db_connecti on ) ; ?> 
</BODYXHTML> 

In this example, every page loads the same file of sitewide utility functions, then loads a file of 
functions specific to that page, then defines variables that will be global for the page, and finally 
intersperses PHP commands in some boilerplate HTML. The content is in columns, and the actual 
content displayed depends on the particular page's functions, which always have the same names, 
but with definitions varying for each page. Changing what's displayed in the columns means either 
changing the per-page functions or (more likely) modifying the database contents. It would be possi- 
ble for a nonprogrammer to do some limited design on this page by operating directly on the HTML 
and being careful to leave the PHP alone. 

The preceding example is just one simplified possibility from a range of ways to divide up the labor 
of displaying a PHP page. Another that we like even better is the heredoc technique that we discuss 
in the section, "The heredoc style," earlier in the chapter. Your particular strategy will depend on the 
type of site, the size of the site, and the styles of the people contributing. 

Finally, note that all these strategies really just adopt a convention about separating logic and display 
in PHP. If you need an even stronger distinction, there are PHP-based templating systems available 
that further insulate the display people from the innards of program logic. One example is YATS 
(Yet Another Template System), available at http : //yats . sourcef orge .net. 



546 



Summary 

Most of the elements of PHP style are desirable in any programming language. You want to write 
readable code, with appropriately abstracted functions, consistent indentation, and explanatory 
comments. You want to stay away from magic numbers, "cloned" code repetition, overuse of global 
variables, and cryptically clever tricks. Your program should work on the inputs you expect, do 
something reasonable with inputs you didn't expect, and have the grace to die informatively in situ- 
ations you really didn't expect. 

Some of the PHP-specific style issues have to do with organizing file inclusions, how intimately you 
mix your PHP with your HTML, and more generally the separation of code from design. A wide 
range of styles are okay here, but you should strive for page-level and sitewide consistency. 
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Connecting PHP 
and PostgreSQL 



You might find that MySQL or even simple text files meet all your data 
storage and retrieval requirements. Nothing about a simple flat data 
structure in a small quantity demands a relational database model. 
However, as we mentioned earlier in this book, you do have choices when 
it comes to databases. In the next chapter, we'll look at a commercial offer- 
ing, Oracle. In this chapter, we'll look at what is possibly the granddaddy of 
the free/open source database alternatives, PostgreSQL (pronounced "post- 
gress-q-1" or sometimes "Postgrey"). 



IN THIS CHAPTER 



Why PostgreSQL 



Administration 



PostgreSQL 



Why Choose PostgreSQL? 

This is the part where the open source purists start waving their hands 
in the air and yelling with uncontrolled excitement! And the excitement 
is easy to understand — PostgreSQL is a true open source database, 
made available under the simple and portable BSD license. You can read 
the almost vanishingly short text of the license at www. postgres.org/ 
1 i cence . html . 

Are you back yet? See, we told you it was short. So reason number one is 
not so much the license itself as the freedom from an 85 page EULA laced 
with sneaky provisions that nobody alive really understands, and that, 
in many cases, you can't even see until you get the box open. By then it's 
too late — all the money's gone. Which brings us to reason number two: 
PostgreSQL is free. We don't mean "free on Mondays, Wednesdays, Fridays, 
and the vernal equinox," nor do we mean "free to the right people," nor 
even the more conventional and arguably understandable "free for noncom- 
mercial use." PostgreSQL is completely and totally free (unless the develop- 
ers change their minds). 
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The term free applies to more than just the cost. As with the GNU General Public License, you can 
alter, repackage, and redistribute PostgreSQL as a standalone product or with your own applications. 
Arguably better than the GPL for businesses, using and distributing PostgreSQL will not "infect" all 
your code with the copyleft. 

Finally, PostgreSQL supports some nifty special features and elements of the ANSI SQL92 and 
SQL99 standards that simply aren't available or fully developed in other databases, as well as the 
ability to work with object and hierarchical data. 

Of course, there are some disadvantages as well. First, consider PostgreSQLs ability to work 
with object and hierarchical data. Wait a minute; didn't we just sell that one as a feature? To the 
PostgreSQL lovers in the audience, it may seem odd to sell these "features" as disadvantages. Don't 
flame us yet. We're just taking a moment to expound on the Keep It Simple Stupid (KISS) philoso- 
phy. You don't need a sledgehammer to drive in a picture nail, and you don't need an object rela- 
tional database to store addresses and phone numbers. 

Some folks will debate this point, but simply put, PostgreSQL is not as fast as MySQL under low- 
load circumstances. At some point, PostgreSQLs more robust design will offer performance advan- 
tages in really large data sets, but on average, MySQL is just that little bit perkier for lots of reads. 
Again, if you have simpler data storage and retrieval needs, there's no need for you to go swimming 
around in the PostgreSQL waters. 

Finally, PostgreSQL is more complicated. Permissions management, for one, is not as clear-cut as it is 
with MySQL. PostgreSQL also offers some features that may cause the novice's eyes to glaze over — 
schemas and stored procedures, while useful, aren't strictly necessary and you may find them to be clut- 
ter. Some people work much better when there are no nonessentials on their desks; the same principle 
may hold true here. 

All these things said, on balance PostgreSQL is a great tool — a superlative tool even — for many 
jobs. Its user base may be smaller than MySQL's, but its devotees tend to be very loyal. We can't 
cover it very comprehensively and still stay within the focus of this book, but if you've gotten this 
far, weighed all the benefits and disadvantages, and you choose PostgreSQL, the rest of this chapter 
should set you off in the right direction. 



Why Object-Relational Anyway? 

Object relational databases (ORDBMS) are a relatively new class of product compared to the rela- 
tional database model that was developed in the early 1970s. In addition to implementing the rela- 
tional model discussed in Chapter 13, ORDBMS borrow from pure object databases, which excel at 
handling media objects, spatial, and series style data. An ORDBMS implements object properties on 
the components of a relational database in order to have the benefit of both worlds. This, in turn, 
facilitates interaction with the object features of PHP. Because PHP's object model is significantly 
more powerful since version 5, there's never been a better time to use these two tools together. 
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This means that choosing PostgreSQL potentially offers the developer greater extensibility. It's fairly 
easy to define and add custom data types, operators, functions, and indexing methods. This has far 
reaching implications for fine-tuning performance; especially when working with particularly com- 
plicated data structures. 

At the data structure level, PostgreSQL tables and objects can benefit from either static or dynamic 
inheritance. That is to say, a child object created from its parent can be made to adopt characteristics 
identical to those of the parent — either just once when it is created, or perpetually (as changes are 
made to the parent, they are passed on to the children). 

This chapter assumes that you have PostgreSQL installed already. If not, please consult the 
PostGreSQL web site at h 1 1 p : / / www .postgresql .org for more information. The web site con- 
tains the most current information on installation and versions for several platforms. 

But is it a database yet? 

Not quite. Like MySQL, Postgres features some command-line utilities in addition to a unified 
interactive client for working with PostgreSQL databases. In this section, we'll use some of the 
command-line utilities stored in the Postgres binary directory to get started. Let's start by inspecting 
what's already there by using the following command, which you need to run as the Postgres user 
(or a user with authority), typically user "postgres" on most newly installed systems. 

psql -1 

It should return something like the following. 

List of databases 
Name Owner | Encoding 

templateO | pgsql | SQ L_ASC 1 1 
templatel | pgsql j SQL_ASCII 
(2 rows) 

Because a database is a mandatory argument to the interactive client and we don't want to work 
directly on one of our template databases, we'll start by creating a single database that we'll use for 
the rest of this chapter. 

createdb sample 

That's all there is to creating a new database, but of course, this is just a blank slate at this point — a 
minimalist canvas based on the template database and on which we will paint a structure to our 
exacting specifications. 

Now we can use the interactive client to work with our database: 
psql sample 
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This will open a copy of samp 1 e and drop us at a prompt along with some instructions. The prompt 
inside the interactive client is different from the shell prompt, which can help you distinguish where 
you are exactly. This is especially useful on a Linux system where multiple shells open at one time is 
an everyday occurrence. The prompt will take the form <databasename>=#, such that our prompt 
will look like: 

sampl e=# 

If you issue the \ ? command from this prompt, you'll get a very long list of everything you can do 
from this prompt, exclusive of SQL specifics, which of course are also supported here. We can't offer 
exhaustive coverage here, but a few key commands are worth exploring: 

■ The \ h command lists available help for all of the supported SQL constructs such as 
SELECT, DELETE, GRANT, and so on. 

■ The \ d command, along with one of its accepted parameters, will display information 
about your database or specific objects in it. Of specific interest are \dt, which will list all 
tables in the current database, and \d <tablename>, which will show the structure of the 
specified table. 

■ \ H turns on HTML output, which is handy for exporting data quickly to the web. In con- 
junction with the \T command you can customize the html output somewhat, and you can 
use \ o to send it all to a file. 

Incidentally, you can call all of these options on the command line when starting psql . Simply sub- 
stitute a hyphen for the slash, and psql will execute the commands in sequence and then exit. For 
even greater utility, you can group these commands in a text file and read them in from the com- 
mand line. 



Down to Real Work 

Let's build a simple structure inside our sample database. This example is necessarily abbreviated, 
but it is designed to give you a quick but useful familiarity with the Postgres and its SQL syntax. If 
you have already exited from our previous example, get back in to the sample database: 

psql sample 

Let's start by defining a simple table to hold the names of some cartoons we really like: 
CREATE TABLE cartoons(id serial, cartoon varcharOO) ) ; 

The following command allows us to check our result: 
\d cartoons 

Table "publ i c . cartoons " 
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Column Type | Modifiers 

h h 

id | integer 

cartoon j character varying (30) j 

Just so we can say we did something relational, we'll create a second table to hold the names of some 
of the characters in these cartoons. 

CREATE TABLE cha racters ( i d int4, character va rcha r ( 15 ) ) ; 

Postgres offers an astonishing 47 data types, so obviously our example barely even scratches the surface. 
To be clear, some of these types are really other types with increasing data specificity built in. (You may 
already be familiar with this concept, commonly called an input mask in other database tools.) 

Now we'll use some SQL to insert a record into the cartoons table. Note that because the serial type 
is just an integer with an auto-increment flag attached, we do not need to specify anything for ID: 

INSERT INTO cartoons (cartoon) val ues( 'Adventures of Scoobiro'); 

The absence of an error message suggests that our efforts have met with success, but it's a good idea 
to check this with a SELECT statement anyway, first to be sure and second because, after a number 
of records have been entered, we may mentally lose track of where the auto-increment value stands. 
We'll need the number to define a relationship with our characters table. 

SELECT * from cartoons; 
id | cartoon 

1 | Scooby 
(1 row) 

Of course, we'd be in pretty bad shape if we managed to mess that one up. Let's also put in a charac- 
ter or two into the characters table. 

INSERT INTO cha racters ( i d , character) VALUESd, 'Shaggy'); 
INSERT INTO cha racters ( i d , character) VALUES(2, 'Daphne'); 

So we've built a database, created a couple of tables, and added a couple of records, just to make sure 
things are going well. Before we make a web application out of this, however, we need to create a 
minimally privileged user — one who can access the tables in our sample database, write to them, 
and read from them, but not modify them or investigate any other aspect of the system. 

In MySQL, users that did not already exist were implicitly created by the GRANT command. While 
Postgres also uses the GRANT syntax, we must explicitly create a user first: 

CREATE USER cartoonfan PASSWORD ' secretword ' ; 

After creating the user, we must give cartoonfan some privileges: 

GRANT SELECT, INSERT, UPDATE, DELETE on cartoons to cartoonfan; 
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GRANT SELECT, INSERT, UPDATE, DELETE 
on characters to cartoonfan; 
GRANT SELECT, INSERT, UPDATE, DELETE 
on ca rtoons_i d_seq to cartoonfan; 

Note that we must issue this command at the table level. For security reasons, the wildcard charac- 
ter does not function in this context. The last command given is necessary for the serial field type 
we selected in the cartoons table. 



PHP and PostgreSQL 

Table 33-1 itemizes the PHP functions for working with PostgreSQL databases. There are many more 
functions than we can possibly elaborate on here. Many of them will make sense only after you have 
gained more familiarity with Postgres. Also, many of the function names for Postgres changed with 
PHP version 4.2. Because this is a PHP6 book, we're going to concentrate on the new names rather 
than the old. 



TABLE 33-1 



Common PostgreSQL Functions in PHP 

Function Behavior 

Takes a single connection string as an argument, enumerating connection 
parameters such as host, database, port, user and password, p g_p c o n n e c t ( ) 
is the persistent version. Returns a connection resource. See the listings below 
for usage examples. 

pg_query ( ) This is the standard pass-through mechanism for sending basic SQL to the 

server. In earlier versions, it was called pg_exec ( ), but this name has been 
deprecated. Although optional, pg_query ( ) likes to see a connection 
resource, followed by a comma before the actual SQL. 

Each of these functions takes at least a query-result resource as an argument 
and returns varying results depending on the function chosen and how it is 
called. Each of these except pg_fetch_al 1 ( ) used to require a counter 
argument if you wished to iterate through the returned rows. This argument 
is still available but is not necessary. These functions differ primarily in 
the results they return, which in the same order as they are listed are: (1) a 
numerically indexed array starting at an offset of 0, (2) an associative array 
with field names as indices, (3) returns both a numeric and an associative 
array, (4) returns the rows and values in object notation, (5) returns a specific 
row and column offset, and (6) returns a multidimensional array of the entire 
result set. 

pg_af f ected_rows ( ) Returns the number of tuples (rows) affected by an I NSERT, UPDATE, or 

DELETE query. 



pg_connect ( ) and 
pg_pconnect ( ) 



pg_f etch_row( ) 
pg_fetch_assoc( ) 
pg_f etch_a rray ( ) 
pg_f etch_ob j ect ( ) 
pg_f etch„resul t ( ) 
pg_f etch_al 1 ( ) 
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Function 


Behavior 


pg__f ree_resul t( ) 


Frees the memory used by a query result. 


pg_num_f i el ds ( ) 


Returns the number of fields in a query result. Use with SELECT statements. 


pg_num_rows ( ) 


Returns the number of rows in a query result. Use with SELECT statements. 


pg_cl ose ( ) 


Closes the PostgreSQL Connection. Takes a connection resource as an 
argument. 



The Cartoons Database 

We'd like to be able to add some cartoons and characters to our database using a handy web-entry 
system. We've deliberately oversimplified our example to get through the key concepts quickly, so it 
should be fairly easy to put together a system that allows us to achieve this task. Listing 33-1 shows 
a welcoming page to our Cartoons database. 



LISTING 33-1 



index, php 

<html > 
<head> 

<title>Cartoons Database</title> 
</head> 

<body> 

<hl>Ca rtoons and Characters Database</hl> 

<p>Welcome to the cartoons and characters database. Existing 
entries are provided below. Use the provided functions to get 
more details and to edit, add or delete entries. </p> 

<?php 

$connect_pa rameters = " host=l ocal host dbname=sampl e 
user=cartoonfan password=secretword" ; 
if ($1 Ink = pg_connect( $connect_pa rameters ) ) { 
$ s Sq 1 = "select * from cartoons"; 
SsResult = pg_query ( $1 i n k , $sSql); 
if ( pg_num_rows ( $s Resul t ) > 0) ( 
print("<table border=\"l\">") ; 
print ( "<tr><th>ID</th><th>Cartoon</th> 

<th>Characters</th></tr>" ) ; 
while ($sRow = pg_fetch_ob j ect ( $s Resul t ) ) ( 
print ( "<tr><th>$sRow->id</th> 
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<td>$sRow->cartoon</td>" ) ; 
$tSql = "select * from characters where 

1 d = ' $s Row->i d ' " ; 
StResult = pg_query ( $tSql ) ; 
print("<td>") ; 

while ($tRow = pg^f etch_ob j ect ( ItResul t ) ) { 
print ( "$t Row -> character "); 

} 

print("</td></tr>"); 

1 

print("</table>"); 
) else ( 

pri nt( "<p>There are not currently any records in the 
cartoon database. < / p > " ) ; 

) 

} else { 

pri nt( "<p>Connecti on to the cartoons database has 
failed</p>") ; 

} 

?> 

</body> 
</html > 



Notice how different our connect parameters are from what we'd use with MySQL. They aren't even 
comma separated! This function is even insensitive to the order in which they are supplied — you 
simply have to use the appropriate parameter name and supply the corresponding value. Additional 
recognized parameters for this function are options, tty, and port. 

The rest of this script reads much like a similar script would for MySQL. A query is defined, we get 
the results of that as an object, issue a second query to get the character data, and use the ubiquitous 
print statement to put it all into a nice HTML table. 

This is fine as far as it goes, but we don't yet have a way to insert, edit, and delete records. In 
Listing 33-2, we create a new form for the purpose of inserting records. 



LISTING 33-2 



insert. php 

<html > 
<head> 

<title>Cartoons Database</title> 
</head> 

<body> 
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<hl>Cartoons and Characters Database</hl> 
<?php 

if ($_POST['action'] == "Insert") { 

$connect_parameters = "host=l ocal host dbname=sampl e 
user=ca rtoonf an password=secretword" ; 
$ 1 ink = pg_connect( $connect_parameters ) ; 
SescCartoon = pg_escape_stri ng( $_P0ST[ ' cartoon ']) ; 
$iSql = "insert into ca rtoons ( ca rtoon ) 

values( ' (SescCartoonl ' )"; 
if ( pg_query ( $1 i n k , $iSql)) ( 

IjSql = "select cu rr val (' cartoon s_i d_seq ' ) as oid"; 
IjResult = pg^query ( $ jSql ) ; 

$ j i d = pg_f etch„resul t ( $ j Resul t , 0, 'oid'); 

$characters_array = explode( "\n", $_P0ST[ ' characters ']) ; 
for($i=0;$i<count( $cha racters_a r ray ) ; $i ++) { 
$char = trim( $characters_array [$i ] ) ; 
SescChar = pg_escape_stri ng ( $cha r ) ; 
$cSql = "insert into characters ( i d , character) 

values($j_id, '(SescChar)')"; 
pg_query ( $cSql ) ; 

} 

pri nt ( " <p>Your submission was successfully inserted. 
You can submit another, if you wish</p>"); 

( else ( 

pri nt( "<p>We were unable to insert the records as 

submitted. You can try again, if you wish</p>"); 

} 

) else j 

pri nt (" <p>Wel come to the cartoons and characters database. 
Enter the"); 

print("name of your favorite cartoon below, and choose 

submi t . </p> " ) ; 

} 

?> 

<form acti on=" i nsert . php" method="post"> 

<p>Enter the name of a favorite cartoon<br> 

<input type="text" name="cartoon"X/p> 

<p>Enter the name of some characters from the cartoon. 

(You can enter more later). Use a hard return to 

separate each name.<br> 

<textarea cols="15" rows="8" name="characters"> 
</texta rea></p> 

<input type="submi t" name="acti on" val ue=" Insert"> 
</f orm> 

<p><a h ref =" i ndex . php" >Return to the main page.</a></p> 

</body> 

</html > 



559 



Part IV 



Other Databases 



This script is doing a lot, so let's review it. Note first the separation of the PHP and HTML elements. 
All of the conditional code appears at the top, and the conditional display requirements are set up 
such that we don't have to weave in and out of PHP to get the job done. We're going to display a 
form even if a submission has just been made so that the user can submit entries one right after the 
other without an intermediate step. The first conditional, at the top of the page, checks to see if the 
page is being called from the form. If not, we print a simple instruction set. If the page is the result 
of a form submission, the fun begins. 

We start with a connection to our database. This item is not tested as we just connected on our 
index page, so we will, perhaps perilously, assume a valid connection. The next step is to generate 
the SQL for the cartoon table from the POST data and insert a new record into the database. The 

next bit is designed to get the insert ID of the inserted cartoon. Actually, PHP offers p g 1 a s t_ 

oi d ( ) for this purpose, but as of this writing, it did not yield the desired result and is currently 
deemed unreliable. 

Once we have the correct ID, we do some manipulation on the contents of the textarea that contains 
our characters. Refer to Chapter 21 on arrays for more on expl ode ( ) . Basically, we're splitting 
the field each place we find a line break and popping the resulting elements into an array. Next we 
call tri m( ) to get rid of the superfluous space character left behind by expl ode () . This is done 
because Windows systems submit an additional \ r wherever a line break occurs. If we explode on 
this as a separator, explode will fail when the form is submitted from Linux, for example, because 
the character is not there. 

Finally, we iterate through the resulting array, putting each character into the characters table with 
its own insert query, and we return a message of success or failure. 

When we went back to test our results, we found a few problems with i ndex . php and so we present 
a revised version in Listing 33-3. We could have just changed the original listing, but this so nicely 
illustrates the debugging process that we've included it this way to point out the improvements. 



LISTING 33-3 



index. php (improved) 

<html > 
<head> 

<title>Cartoons Database</title> 
</head> 

<body> 

<hl>Cartoons and Characters Database</hl> 
<?php 

if ($_POST['action'] == "Insert") { 

$connect_pa rameters = " host=l ocal host dbname=sampl e 
user=ca rtoonf an password=secretword" ; 

Slink = pg_connect( $connect_pa rameters ) ; 
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SescCartoon = pg_escape_st ri ng ( $_P0ST[ ' ca rtoon ' ] ) ; 
SiSql = "insert into ca rtoons ( cartoon ) 

v a 1 u e s ( ' ($escCartoon( ' )"; 
if ( pg_query ( $1 i n k , $iSql)) { 

IjSql = "select cu rr val (' cart oons_i d_seq ' ) as oid"; 
IjResult = pg_query ( $ jSql ) ; 

$ j i d = pg_f etch_resul t ( $ j Resul t , 0, 'oid'); 

$characters_array = explode( "\n", $_P0ST[ ' characters ']) ; 
for($i=0;$i<count( $cha racters_a r ray ) ; $i ++) { 
$char = trim( $characters_array [$i ] ) ; 
SescChar = pg_escape_st ri ng ( $cha r ) ; 
$cSql = "insert into cha racters ( i d , character) 

values($j_id, '(SescChar)')"; 
pg_query ( $cSql ) ; 

) 

pri nt( "<p>Your submission was successfully inserted. 
You can submit another, if you wish</p>"); 
( else { 

print("<p>We were unable to insert the records as submitted. 
You can try again, if you wish</p>"); 

} 

) else j 

pri nt( "<p>Wel come to the cartoons and characters database. 
Enter the"); 

print("name of your favorite cartoon below, and choose 
submi t . </p> " ) ; 
} 

?> 

<form acti on=" i nsert . php" method="post"> 

<p>Enter the name of a favorite cartoon<br> 

<input type="text" name="cartoon"X/p> 

<p>Enter the name of some characters from the cartoon. 

(You can enter more later). Use a hard return to 

separate each name.<br> 

<textarea cols="15" rows="8" name="characters"> 
</textarea></p> 

<input type="submi t" name="acti on" val ue=" Insert") 
</f orm> 

<p><a h ref =" i ndex . php" >Return to the main page.</a></p> 

</body> 

</html > 



First, we added a link to our now finished insert form. Second, we are now passing the action 
parameter via our submit button, purely for the sake of orderliness. We also encountered a prob- 
lem with our characters display. When we submitted a character with a space in its name (okay, we 
admit, we were trying to submit Wonder Woman), it was unclear where one character ends and the 
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next one begins. Using a little regex and string concatenation, we've now caused this to display as a 
comma-separated list. 

Now we need a form for editing records. Listing 33-4 is what we've come up with. 



LISTING 33-4 



edit.php 

<html > 
<head> 

<title>Cartoons Database</title> 

</head> 

<body> 

<hl>Cartoons and Characters Database</hl> 
<?php 

$connect_parameters = " host=1 oca 1 host dbname=sampl e 
user=ca rtoonf an password=secretword" ; 
$ 1 ink = pg_connect ( $connect_pa rameters ) ; 
if ($_POST['action'] == "Update") ( 
SescCartoon = pg_escape_stri ng( $_P0ST[ ' cartoon ']) ; 
$escld = pg_escape_stri ng( $_P0ST[ ' f ' ] ) ; 
$sSql = "update cartoons set cartoon = ' { $escCa rtoon } ' 
where id = ' { $ e s c I d } " ; 
if (pg_query($sSql ) ) { 

$dSql = "delete from characters where id = '{$escld}'"; 

pg_query ( $dSql ) ; 

$characters_array = explode( "\n", $_P0ST[ ' characters ']) ; 
for($i=0;$i<count( $cha racters_a r ray ) ; $ { 
$char = triin($characters_array[$i ] ) ; 
SescChar = pg_escape_st r i ng ( $cha r ) ; 
if ($char <> ' ' ) { 

$cSql = "insert into characters 
(id, character) 

values({$escld) , ' (SescChar) ' )" ; 
pg_query ( $cSql ) ; 

) 

} 

pri nt( "<p>Your edits were successfully posted . </p> ") ; 
) else ( 

print( "<p>Update of record $_P0ST[f] f ai 1 ed . </p>" ) ; 

1 

print("<p><a href = \ " i ndex . php\ " >Return to the main 
page.</a></p>"); 

I else ( 

$escld = pg_escape_stri ng ( $_GET[ ' f ' ] ) ; 

$sSql = "select * from cartoons where id = j$escld}"; 

SsResult = pg_query ( IsSql ) ; 
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$sRow = pg_f etch_ob j ect ( $s Resul t ) ; 

print("<form acti on=\ "edi t . php\ " method=\"post\">" ) ; 
pri nt( "<p>Edi t the name of a favorite cartoon<br>" ) ; 
pri nt ( " <i nput type=\"hidden\" name=\"f\" 

value=\"$_GET[f]\">"); 
pr i nt ( " <i nput type=\ " text\ " name=\"cartoon\" 

val ue=\"$sRow->cartoon\"X/p>" ) ; 
pri nt( " < p > E d i t the name of some characters from 

the cartoon. "); 
print("(You can enter more later). Use a hard return to "); 
print( "separate each name.<br>"); 
print( "<textarea cols=\"15\" rows=\"8\" 

name=\"characters\">" ) ; 
$escld = pg_escape_stri ng( $_GET[ ' f ' ] ) ; 
$ c Sq 1 = "select * from characters where id = j$escld}"; 
ScResult = pg_query ( $cSql ) ; 
while ($cRow = pg_f etch_ob ject ( ScResul t ) ) { 
pri nt ( " $cRow->cha racter\ r\n " ) ; 

} 

print("</textarea></p>"); 

pri nt( "<i nput type=\ " submi t \ " name=\ " acti on\ " 

val ue=\ " UpdateX " > " ) ; 
pri nt( "</form>" ) ; 
print("<p><a href=\"index.php\">Return to the main 
page.</a></p>"); 

} 

?> 

</body> 
</html > 



Like insert, php, edit.phpisa recursive action form. The form post is sent to the same script and 
the action taken depends, essentially, on the contents of a hidden variable, $acti on . In the absence 
of this variable, we just retrieve the records from the cartoons and character tables and drop them 
back in the form much as they appeared in the original insert form. To parse the characters back 
into their original positions, note that we have essentially reversed the explode function we used in 
insert. php, but we'll shift it back into forward when we go to post the updates. 

One thing you might find strange is that before we post the updates to the characters table, we delete 
all the entries. This is because we haven't created a unique key for each character, so there isn't a 
way to conveniently refer to an individual record unambiguously. Yes, this is a design flaw. In a big- 
ger project, it would be a substantial design flaw. But there are some advantages to the way we've 
done this. A form to update both characters and cartoons in the same action is much easier to do in 
this scenario. It would be quite a bit more code intensive, though certainly feasible, to add a serial ID 
to the characters table, retrieve all three fields, set up a multidimensional array in our form, retrieve 
it, and process it in our script such that multiple records are updated in a single operation. You get 
the idea. Sometimes it's okay to opt for simplicity. 
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Finally, we've made a few changes to i ndex . php, which we're going to show you in Listing 33-5. All 
we've done is added a way to get at the edit functions and a simple routine for deleting a record, par- 
ent and children, in one operation. 



LISTING 33-5 



index. php (final) 

<html > 
<head> 

<title>Cartoons Database</title> 
</head> 

<body> 

<hl>Cartoons and Characters Database</hl> 

<p>Welcome to the cartoons and characters database. Existing 
entries are provided below. Use the provided functions to get 
more details and to edit, add or delete entries. </p> 

<?php 

$connect_parameters = " host = l oca 1 host dbname=sampl e 
user=ca rtoonf an password=secretword" ; 
if ( $ 1 ink = pg_connect($connect_parameters ) ) ( 
if ($_GET[' action'] == "d") { 

$escld = pg_escape_st r i ng ( $_GET[ ' f ' ] ) ; 

$dSql = "delete from characters where id = '{$escld}'"; 

pg_query ( $dSql ) ; 

$dSql = "delete from cartoons where id = '{$escld}'"; 
pg_query ( $dSql ) ; 

1 

$sSql = "select * from cartoons"; 
SsResult = pg_query ( $1 i n k , $sSql ) ; 
if ( pg_num_rows ( SsResul t ) > 0) ( 
print("<table border=\"l\">"); 
print ("<tr><th>ID</th><th>Cartoon</th> 

<th>Characters</th><thX/thX/tr>" ) ; 
while ($sRow = pg_f etch_ob ject ( $s Resul t ) ) ( 
print ("<trXth>$sRow->id</th> 

<td>$sRow->cartoon</td>" ) ; 
$tSql = "select * from characters where id = ' $sRow->i d ' " ; 
StResult = pg_query ( $tSql ) ; 
print("<td>") ; 
$character_stri ng = ""; 

while ($tRow = pg_f etch_ob j ect ( ItResul t ) ) { 
$character_stri ng .= "$tRow->character , "; 

1 
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$new_character_stri ng = ereg_repl ace( " ( , )$", "", 

$cha racter_stri ng ) ; 

print ( " $new_cha racter_stri ng</td>" ) ; 

print ( "<td><a href =\ " edi t . php?f =$s Row->i d\ " >Edi t</a> | " ) ; 
print(" <a href=\"index.php?f=$sRow->id&action=d\"> 
Del ete</a></td></tr>" ) ; 

} 

print("</table>") ; 
( else { 

pri nt( "<p>There are not currently any records in the 
cartoon database. < / p > " ) ; 

} 

print("<p><a href =\ " i nsert . php\ " >Add a Record</aX/p>" ) ; 
) else { 

pri nt( "<p>Connecti on to the cartoons database has 
fai 1 ed</p>" ) ; 
} 

?> 

</body> 
</html > 



Summary 

PostgreSQL is an interesting and powerful database tool. Although we did not comprehensively 
cover all of its utility here, we have shown you enough basics to get started with it. Check the PHP 
documentation at www .php.net/pgsql for a comprehensive listing of PostgreSQL functions. 
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PEAR DB is one of several wrappers around PHP's database exten- 
sions that seek to generalize the concept of a database connection. 
PEAR DB is fully object oriented. With PEAR DB implemented in 
your software, you'll find it easier to allow your application's users to select 
from several databases (the list of supported databases includes all the 
majors, and plenty of second-string players as well). You may also find it 
easier than before to handle errors and react to unexpected occurrences 
that take place during connections and queries. 

This chapter aims to explain what PEAR DB is all about. It's not hard, but it 
is important that you understand PEAR DB in theory and practice, because 
there are substantial pros and cons to its use. We start with a general dis- 
cussion of the benefits and costs of a database abstraction layer; then we 
explain the basics of using the PEAR DB package. 

For reference, examples, and further explanations of concepts, have a look 
at the PEARDB web site athttp://pear.php.net/package/DB. 



For general information on PEAR and instructions on how to 
locate and install PEAR libraries, see Appendix E. 



IN THIS CHAPTER 



Pear DB concepts 
Pear DB functions 
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Pear DB Concepts 

There are a number of concepts in PEAR DB that you must understand to work with the class effec- 
tively. These include: 

■ Data Source Names (DSNs) 

■ Connection 

■ Query 

■ Row retrieval 

■ Disconnection 

The following subsections explain each of these items in turn. 

Data Source Names (DSNs) 

A Data Source Name (DSN) is simply a text string that describes where a database is and how to 
access it. A DSN is very much like a URL for a database. Because databases almost always have user- 
level access control, DSNs specify usernames and passwords. Note that DSNs specify the database to 
which your program is connecting, not the table within the database. 

In order to form a DSN, you have to come up with a number of values: 

■ The type of database you're connecting to (FrontBase, MySQL, Oracle, or whatever you 
fancy) 

■ The hostname or IP address of the machine running the database server 

■ The database name 

■ The username you want the software to use 

■ The corresponding password 

Very often, you'll need to access these values in order to create DSNs in several different but related 
PHP programs. For that reason, it often makes sense to assign the literal values to variables in a spe- 
cial program that's imported elsewhere. Such a program might look like this (call it dbSpecs . php): 

< ? p h p 

$phptype = ' mysql ' ; 

SdbHost = ' spock ' ; 

$database = 'inventory'; 

$username = ' phpUser ' ; 

$password = ' sesame ' ; 
?> 
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The only odd bit there is the value for $phptype. Its value is a standard string that corresponds to a 
specific database (MySQL, in this example). The related sidebar shows all valid options for the data- 
base identifier. 



Valid Database Identifiers for DSNs 

Mere's a list of all the database management servers supported by PEAR DB, complete with the strings you 
should use to identify them in DSNs. 

■ FrontBase (f bsql ) 

■ InterBase (i base) 

■ Informix (i fx) 

■ Mini SQL (msql) 

■ Microsoft SQL Server (mssql ) 

■ MySQL (my sql ) 

■ Oracle 7/8/8 i (oci8) 

■ ODBC(odbc) 

■ PostgreSQL (pgsql) 

■ SyBase (Sybase) 



Having defined your variables in a simple library, when you want to create a DSN, you can import 
dbSpecs.php and have access to its values. The advantage is that if the values indbSpecs.php 
ever change, you need to modify them in just one place. The import statement is simple: 

require_once( 'dbSpecs.php' ) ; 

With that imported, you can use the values defined in dbSpecs . php to create a DSN. Remember, 
though, that you need to register the variables if you create your DSN inside a function (this is a 
standard characteristic of PHP variable scoping): 

global $phptype; 
global $hostspec; 
global $database; 
global $username; 
global $password; 

Once you have the values available, stringing them together into a properly formatted DSN is pretty 
simple. The standard format looks like this: 

$dsn = " $phptype : / /$username : $password@$hostspec/$database " ; 
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There are more obscure options available for use in defining DSNs. They're described in detail at 
http://pear.php.net/manual/en/package.database.db.intro-dsn.php. 



When you have a valid DSN, it's a simple matter to tell PEAR DB to establish a connection to the 
database the DSN describes. The line of code you need looks like this: 

$db = DB :: connect ( $dsn ) ; 

If the connection attempt succeeds, everything's great — $db contains an object representing a con- 
nection to the database, and you can run queries against that object (among other amusing and educa- 
tional activities). Because you're a good programmer, though, you should allow for errors. Here's how: 

if (DB: :isError($db)) ( 
die($db->getMessage()); 



The i s E r r o r ( ) method returns true if the database object — $ d b in this case — represents a con- 
nectivity error, and false if not (meaning, if the connection succeeded). In this case, the code aborts 
if the database connection wasn't successfully established. 



Building on the successful database connection, you'll typically want to run a query against the 
database. That's accomplished with Structured Query Language (SQL), which is described in detail 
in Chapter 13. 

The customary procedure is to write your SQL query as a string and stuff that string into a variable 
called $sql or $query: 

$sql = "SELECT cityName FROM cities ORDER BY cityName"; 

Then use that variable as a parameter for the q u e ry ( ) method of your database object (in other words, 
of the variable that represents the connection to the database), and assign the results to another variable: 

$result = $db->query ( $sql ) ; 
Once again, allow for the possibility of error: 

if (DB::isError($result)) 

SerrorMessage = $resul t->getMessage( ) ; 
di e( lerrorMessage) ; 

} 




As always, we recommend storing database connection variables outside the web tree for 
greater security. 



Connection 



Query 
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Row retrieval 

As a result of the query ( ) operation, $resul t contains a result set. A result set is some number of 
rows (possibly zero). 

To extract values from the result set, use awhile loop like this one: 
$1=0; 

while ($row = $resul t->fetchRow( ) ) ( 
SreturnArray [$i ] = $row[0]; 
++$i ; 

1 

This loop exists to use the fetchRow( ) function against every row in the result object, thus extracting 
it. Because we know the result set has only one column (the SQL statement requested only ci tyNartie), 
we can take the first element of every row array ($ row [ 0] — the only element) and put it into another 
array, SreturnArray. Presumably, we'll do something useful with SreturnArray later, but that's not 
anything to do with PEAR DB directly. 

Disconnection 

When a database connection has served its purpose, use the discornect() method of the database 
object to free the resources associated with the connection: 

$db->disconrect( ) ; 

It's important to remember to do this; otherwise, the connection remains active until it times out 
(a long time). This means that the database server, in an active environment, could become over- 
whelmed with zombie connections. 

A complete example 

It may be beneficial to have a look at a complete function that performs database access operations 
by way of the PEAR DB class. 

The role of this function, which we'll call get Items . php, is to extract all items from a Microsoft 
SQL Server database called INVENT0RY_i tern. To return all items, we need a SELECT statement that 
draws all columns out of the INVENTORY _i tern table. Because INVENTORY _i t em has no foreign 
keys (an assumption made for the purposes of this illustration), extracting its data involves only 
sending a straightforward SELECT statement to the database server via a PEAR DB connection. 

Let's examine getltems.php line by line to see how this is done . 

<?php 

require_once ('DB.php'); 
require_once ('dbSpecs.php'); 
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First, we must import the PEAR DB classes and dbSpecs.php, which contains information about 
the database server and security credentials for it (it's listed earlier in this chapter). 

function getltems() 
{ 

global $phptype; 
global $hostspec; 
global $database; 
global $username; 
global $password; 

In the function, the five global variables (from dbSpecs.php) must be declared for them to be 
accessible. 

$dsn = " $phptype : //$username : $password@$hostspec/$database" ; 
$db = DB: : connect ( $dsn ) ; 
if (DB: :isError($db)) { 
die($db->getMessage( ) ) ; 

} 



Using the PEAR DB procedure discussed earlier in this chapter, the program connects to the data- 
base server. The program checks for an error condition and aborts if one is found to exist as a result 
of the connection attempt. 

The program then defines the SQL statement to be run against the database to which a connection 
has been established: 

$sql = "select id, desc, weight, packageQty, unit, supplierlD, 
cost from INVENTORY_i tern" ; 

That's the SQL query that is to be sent to the database server. Note that we specify the columns, 
even though we want all of them. That way we know what order the columns will be in when results 
come back. 



Sresult = $db->query ( $ s q 1 ) ; 
if (DB::isError($result)) { 

SerrorMessage = $resul t->getMessage( ) ; 

di e ( SerrorMessage ) ; 

} 



The program sends the query to the database and checks to see if an error message comes back. 

SreturnArray = arrayO; 

while ($row = $resul t->fetchRow( ) ) { 

$i d = $row[0] ; 

$desc = $row[l] ; 

$weight = $row[2] ; 

SpackageQty = $row[3]; 

$uni t = $row[4] ; 
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SsupplierlD = $row[5]; 

$cost= $row[6]; 

$returnArray[] = 

array('id' => $id, 'desc' => $desc, 'weight' => Sweight, 
'packageQty' => SpackageQty, 'unit' => $unit, 
'supplierlD' => SsupplierlD, 'cost' => $cost); 

1 

$db->disconnect( ) ; 
return SreturnArray ; 
} 

?> 

The remainder of the program involves setting up an array called SreturnArray. Itis filled with 
a series of subarrays, making it a two-dimensional array. The subarrays are associative arrays; 
their keys correspond to column names in the database, and their values come from each row of 
$resul t. 



PEAR DB Functions 

The PEAR DB class is fairly extensive, with members far more numerous than the widely used ones 
covered already in this chapter's examples. Most of the other members are specialized, and as such 
come in handy only under particular circumstances. 

This section summarizes some of the most useful members of the PEAR DB class but is not compre- 
hensive. Be sure to refer to http://pear.php.net/manual/en/package.database.php for the 
official list and documentation. 

Members of the DB class 

The DB class itself is the main PEAR DB class, and is used to represent a connection to a database (or 
an attempt to create one). Methods include: 

■ DB::connect(): Uses a DSN to connect to a database 

■ DB: :isWarning( ): Returnstrueifa connection attempt yielded a warning 

■ DB::isError(): Returns true if a connection attempt yielded an error 

Members of the DB_Common class 

The methods of the DB_Common class may be invoked on a database connection for such purposes as 
executing queries and getting information from the database. Methods include: 

■ DB_Common : : af f ectedRows ( ) : Returns the number of rows affected by a query. 

■ DB_Common : :disconnect( ): Disconnects a database connection. 
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DB 


Common : 


getAl 1 ( ) : 


Rptnrns all rnw^ returned hv a nnprv 


DB 


_Common : 


getAssoc 


) : Returns all rows as an associative array. 


DB 


_Common : 


getCol ( ): 


Returns all rows in a specified column. 


DB 


_Common : 


getOne ( ) : 


Returns the value in the first column of the first row. 


DB 


_Common : 


getRow( ) : 


Returns the first row. 


DB 


_Common : 


nextld( ): 


Allows you to exercise extra control over the establishment of 



unique i d values, as in a primary key column. 

■ D B_C ommon::query(): Sends an SQL query string. 

Members of the DB_Result class 

The members of the DB_Resul t class may be invoked on a result set, which is what exists after a 
query is run on a database. 

■ DB_Resul t: :fetchInto( ): Extracts a row into a specified variable 

■ DB_Resul t : : fetchRow( ): Extracts the next row 

■ DB_Resul t : : f ree ( ) : Destroys the result set 

■ DB_Resul t::numCols(): Returns the number of columns in a result set 

■ DB_Resul t: : n urn Rows () : Returns the number of rows in a result set 

Summary 

This chapter introduced PEAR DB, the class with which PHP makes database connectivity more 
generic. You saw that PEAR DB is designed to make the task of switching from one database server 
to another extremely easy and that it generally succeeds in this design goal. In many cases, switch- 
ing connectivity from one database server to another requires the modification of only one word in a 
whole database-enabled program. 

The process of connecting to a database via PEAR DB involves establishing a DSN, which is essen- 
tially a URL for a database. The DSN specifies the hostname of the database server, as well as the 
database name, and the username and password required to gain access to the database. With a 
valid DSN, it's possible to establish a connection, run a query, and extract rows of values from the 
query's results before disconnecting. PEAR DB also includes methods — which you should take care 
to use — for detecting error and warning conditions. 

Much more information on Pear DB can be found at its official web site http://pear.php.net/ 
package/DB. 
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Oracle databases are extremely powerful, reliable, and fast for cer- 
tain kinds of queries. They are also a testament to the power of 
marketing, as they enjoy a mystique unmatched by any other data 
storage product. In this chapter, we try to cut through the hype and give 
you a practical foundation in using Oracle with PHP. 



7JP 



i Much of the information in this chapter is also applicable to 
™ IBM DB2, which PHP connects to using the ODBC interface, 
InterBase, and similar products. Much of Oracle's functionality is also dupli- 
cated by PostgreSQL, although this open source database unfortunately has a 
considerably different API than any other database. The point of this chapter 
is not to push Oracle over another product; it is to introduce a market-leading 
commercial database to those who want to learn how to use it. Feel free to 
mentally substitute DB2 or PostgreSQL for every instance of Oracle in the 
following section. 



IN THIS CHAPTER 



When do you need Oracle? 
Oracle and web architecture 
Using Oracle functions 
Project: Point editor 
Project: Batch editor 



When Do You Need Oracle? 

We have never had a prospective employer or client for a PHP job who 
did not at least mention the possibility of using Oracle. Ironically, the one 
organization that really needed this type of functionality was very slow 
to adopt it, whereas everyone else didn't need Oracle at all but wanted to 
architect current development around the theoretical possibility that they 
might need it later. In an anecdotal way, this experience testifies to the 
niche Oracle Corporation has managed to carve out in the minds of the 
entire software industry. 
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Through a powerful marketing machine (and, of course, a fine product), Oracle has managed to 
make its name synonymous with size, scale, and (by implication) success. Therefore, every busi- 
nessperson who dreams of making it big in any business having to do with data has a fantasy 
that someday he or she will need and be able to afford an Oracle installation. When the humble 
PHP developer says, "You don't need Oracle," this is too often taken as equivalent to saying, 
"You're never going to amount to anything" — in other words, a big splash of cold water right in 
the face of the entrepreneur or manager. This does not tend to endear the humble PHP developer 
to the person writing the checks, even if your motivation is to save money and trouble for the 
boss. Sometimes reality cannot compete with fantasy, even in the supposedly hard-headed world 
of business. 

So how do you realistically decide whether you need Oracle (or a workalike) or not? Certain well- 
understood factors are tripwires. If you are in one of these situations, your pondering is done. If not, 
the chances are very high that your needs could be met perfectly well — perhaps even better — by a 
cheaper, easier-to-use database. 

Money 

If you keep track of money or anything that can be converted to money (credit card charges, equi- 
ties, airline miles, royalty payments, vacation time), you need the transactional model. Done, end of 
story, move on to the next thing. Not only are these things important to track end to end, but people 
tend to get very annoyed when you fail to do this correctly. You do not want to be matching up 
failed charge attempts or stock purchases programmatically. 

The only exception is if you do not handle the financial part of the transaction yourself. It's fairly 
common these days for even pretty large web sites to route their fulfillment transactions through 
some third party. If you are willing to send a customer off to your fulfillment partner, and then take 
its word on whether the transaction was completed successfully or not, you can offload the transac- 
tional database requirements onto your partner. 

Other rivalrous resources 

If you track other kinds of rivalrous resources on a large scale — airline tickets, concert tickets, 
inventory — you very likely need a transactional database. Note that the operative term is large scale. 
This feature applies only if you are in imminent danger of having colliding writes, meaning that the 
chances are good that, between the time you check whether a resource is available and the time you 
write it into another table, someone else may have claimed it. In other words, this stricture applies 
to computer-scale time. If you run a web site that takes a couple hundred new registrations a day, 
you are not going to run into this kind of problem except as a rare fluke. 

Huge data sets 

Again, huge is the key. Millions of rows is not huge. If you will never realistically get past tens of mil- 
lions of rows, you don't need Oracle for sheer scalability. 
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Lots of big formulaic writes or data munging 

Oracle's stored procedures can increase speed immensely in situations where you have the same kind 
of big write or data processing happening all the time. Stored procedures amount to moving part of 
the code into the database itself. Processes that use these stored procedures will get done faster than 
processes that don't, because you've already told the database exactly what to do in a certain situation. 
Databases without stored procedures require all instructions to come from the PHP program, which 
is far slower in loops than simply handing off the input data and letting the database run with it. 

For instance, if you run an e-commerce site that just takes inputs from one kind of order form and 
nothing else, you'll get increased overall speed from a stored procedure. The database will not have 
to finish one step and then wait for the program to tell it the next step or to feed it the next bit of 
data. PHP will simply open up the connection, shovel some data down the pipe as fast as it can, kick 
off the stored procedure, and possibly wait for a response. 

Stored procedures obviously add value in cases where there is massive data munging happening on 
the database side. For instance, if you have a big data warehouse that takes a described data set and 
performs lots of analytical operations on it, then returns the results of those operations, you will 
very likely get much improved performance from a stored procedure. 

Remember that stored procedures don't help you in cases where there is variability in the process. 
For instance, if you make ad hoc queries on a data warehouse all the time, those queries will be 
extremely slow compared to a query that you make every day using a stored procedure. Also, you 
have to use stored procedures pretty often to choose a database on this basis. A whole infrastruc- 
ture needs to be in place for you to derive benefits from stored procedures, and you need to decide 
whether it's worth the very real costs to build this infrastructure. 

Triggers 

Triggers are just what they sound like: The database keeps track of state; when some kind of trig- 
gering event happens, it kicks off one or more stored procedures. You need triggers if you need to 
respond to certain well-defined data events in real time and are willing to give up global performance 
to do it. If your changes do not have to occur instantly — if, for instance, they can happen once an 
hour — you are probably better off without triggers as you can schedule stored procedures to run 
periodically. On the other hand, if you have to detect changes every second or so, triggers will be 
much more efficient than cronjobs or other alternatives. This is a pretty rare feature for a web archi- 
tecture, so think hard about whether you need triggers. 

Legal liability 

Finally, there are nontechnical reasons why you might need Oracle — one of which is legal liability. 
Imagine that you run a business that is in some kind of personal information space — credit reports 
or medical records, perhaps. If somehow two records get mixed up, you would face significant legal 
liability for this most private type of information. One line of defense is to assert that you followed 
industry standard practices to safeguard data integrity, including use of the industry-leading database 
system. The tens of thousands of dollars you spend on an Oracle installation may seem cheap in this 
circumstance. 
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Bottom line: two-year outlook 

Even if you don't need any of these features now, it behooves you to think whether you might need 
them sometime in the foreseeable future. But don't try to build a web architecture for the ages — 
new things happen so fast on the Internet that cathedral-builders are made fools of daily. 

In general it seems like a two-year window is about right unless your needs are changing exception- 
ally quickly or slowly. If you don't see any of the preceding conditions looming on your horizon 
within two years or so, don't worry too much about switching to Oracle. 

On the other hand, if you meet any of the preceding criteria, don't waste time — you need Oracle or 
one of its functional competitors. 

Oracle and Web Architecture 

Having an Oracle database on your backend implies certain things about your architecture and 
your web development team. Do not think you can finesse these issues. If you're not ready to accept 
them, you're not ready for Oracle. 

Specialized team members 

The minute you have an Oracle installation, you need at a minimum a DBA and a PL/SQL program- 
mer. Do not think that it's at all reasonable to expect web developers or binary programmers to take 
over any of the tasks of these positions, as they often are expected to do with simpler data stores. 
Database tasks such as installation, tuning, refreshing, setting indexes, maintaining hot backups, 
and writing complex stored procedures are very highly specialized skills, which require specialized 
training and probably certification. 

One of us once worked in a situation where (mercifully briefly) a team of programmers tried to get a 
database installed and running with help from a couple of contractors rather than full-time Oracle 
professionals. This was an indescribably miserable experience for everyone concerned, with data 
corruption and bizarre server issues on a daily basis. The minute a real DBA and PL/SQL program- 
mer came in, the situation improved immeasurably — 10-second queries became half-second que- 
ries, and so on. There's a reason that these professionals make the big bucks, and we can assure you 
that you don't want to learn why the hard way. 

Shared development databases 

Due to the cost and complexity of the database, you will almost certainly need to limit the number 
of separate development instances in the office. This means that if all your developers are working 
against one development database that gets corrupted or otherwise goes down, the whole team will 
be out of commission until the problem can be resolved. On the other hand, MySQL and SQL Server 
make it easy for every developer to run a local instance if necessary. 
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And don't even think about cheating on your licenses — an Oracle software license audit is nothing 
you want to experience. 

Limited schema changes 

Lighter-weight databases make it possible to make schema changes on the fly — even in production. 
In Oracle, this is not a good idea. It's more difficult to add new database-driven features quickly 
because of the time and planning necessary to successfully create schema changes. With Oracle, you 
really need to design the entire schema in advance (as you're supposed to do but never quite take the 
time to complete). 

Tools (or lack thereof) 

Be prepared to invest significantly in tools. Almost no tools are available on the market to help you 
with Oracle from a PHP platform specifically. More generally, Oracle is not interested in data sets 
smaller than a few tens of thousands of records, and many of the tools available are not really worth 
running on data sets smaller than that. 

Replication and failover 

Some database servers, like MySQL, work best in clusters with one master handling writes while a 
bunch of slaves serve up reads. This means that, for maximum efficiency, MySQL code should be 
written to take advantage of multiple connections on a single page — each MySQL function specify- 
ing a particular resource handle, for instance. 

Oracle, however, works best in a single monolithic instance. Remember that eBay grew to be one of 
the biggest sites on the web, and suffered many costly site failures, before even beginning to move 
away from a monolithic database instance. This tends to create a single point of failure model that 
affects all aspects of deployment — after all, what's the point in having massive redundancy in web 
servers when all of them could be struck down by a single hardware problem on the database server? 
Most important for PHP developers, writing code for Oracle will not require you to juggle multiple 
connections on a per-page basis, as there is little to be gained by this practice. 

Data caching 

One piece of good news is that Oracle can be configured to cache data. This means that if you make 
the same query over and over for a while — for instance, you validate the user against the database 
on every page load — the database will only actually perform the query the first time. On subse- 
quent requests, it will just serve up the result from some cache memory, for a much faster result. 
This means that you will not have to implement a custom data-caching scheme of your own, which 
is a very expensive and tricky task. 

However, we should mention that lighter-weight databases are rapidly catching up to Oracle's data 
caching capabilities for small queries. Microsoft SQL Server is reported to have excellent data cach- 
ing, and MySQL implemented it for the first time in version 4.0.1. 
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Using OCI8 Functions 
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The remainder of this chapter explains how to use PHP's Oracle functions. If you have no 
familiarity with Oracle at all, and especially if you do not have extensive experience with 
other SQL databases, you will probably also need to consult an Oracle reference such as Oracle 11g 
For Dummies (Zeis and Ruel, Wiley, 2009). 

PHP has two Oracle extensions: Oracle and OCI8. The Oracle extension is deprecated for versions of 
Oracle after 7 and should be avoided if at all possible. The OCI8 extension is literally dozens to hun- 
dreds of times faster at most queries, and also allows much better handling of cursors. We will not 
be describing the Oracle extension at all; use OCI8 from the beginning. 



7jF~ 



Although Oracle is currently in version 11, the OCI8 extension is still the one you want. 
Apparently the PHP team has simply decided not to change the name with every update. 



If you walk through a couple of typical Oracle queries step by step, you can see that the procedure is 
a bit different from that for MySQL or SQL Server: 

$name = str_replace( , , $name); 

$query = "SELECT product_id FROM product 

WHERE product_name = '$name'"; 
$stmt = OC I Pa rse ( $conn , $query); 
OCIExecute($stmt, OCI_DEFAULT) ; 
$err_array = OC I Error ( $s tmt ) ; 
if ($err_array) { 

$err jnessage = $err_array[ 'message '] ; 

$$error_str = $err_message ; 

OCIFreeStatement($stmt) ; 
} else ( 

OCIFetchStatement($stmt, $res, OCI_RETURN_NULLS) ; 
OCI FreeStatement ( $ strut ) ; 

} 

$product_id = $ res [ ' PR0DUCT_I D ' ] [0] ; 

Right away you will notice differences such as string escaping, parsing and executing, memory 
management, and fetching data sets. We explain these differences in more detail in the sections 
that follow. Please refer to the preceding code block for all references that do not have their own 
code examples. 



Escaping strings 

Remember that Oracle uses Sybase-style string escaping — in other words, it escapes single quota- 
tion marks with a single quotation mark, not with a backslash. This means that you will have to 
manually escape every string, since magi c_quotes has the wrong effect, or you have to set Sybase- 
style magic quotes in your php . i n i file. 
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Parsing and executing 

In most other databases, you send a SQL query over the pipe, and it returns either a value or an 
error message. In Oracle, you have an intermediate step in which you must parse the query for cor- 
rectness. If your SQL is bad, the query will never be sent to the database. An invalid SQL query will 
return an Oracle error code via 0 C I E r r o r ( ) . 

In most cases, the query will be fine and you'll move right to executing the query. This is your 
opportunity to specify a mode for your query, either 0CI_C0MMIT_0N„SUCCESS or 0CI_DE FAULT , 
which does not auto-commit. We generally do not auto-commit because we like to know when a 
rollback is necessary, but this is largely a matter of preference. Of course, for SELECT statements it 
doesn't matter which mode you choose because no commitment or rollback is happening anyway. 
See the section on transactionality later in this chapter. 

Error reporting 

Oracle error reporting is also unique. For one thing, you can specify whether you're asking for a 
global-, connection-, or statement-level error. A global error is a failure to get a connection. A con- 
nection error is an invalid SQL statement that chokes at the parse stage — remember, it isn't a 
statement yet, so it can't be a statement-level error. A statement error involves a problem with a 
properly parsed statement. 

The product of OC I Error () is an associative array, where code is the error code and message is a 
text string. 

Memory management 

In Oracle, you are expected to do some memory management manually. In particular, it's a good 
idea to free statement memory when you're done with the statement handle, and cursor memory 
when you're done with the cursors. Theoretically, all the memory will be reclaimed at the end of 
every script, but if your scripts are big you might want to free memory as you go. 

Ask for nulls 

If you want null values in your data set, you have to ask for them in the fetch function. Otherwise, 
Oracle will not return the field name as part of its associative array, and thus an array member you 
expect to see will not exist. Many other databases will automatically return the null values. 

Fetching entire data sets 

Oracle has four fetching functions: OCIResult,OCIFetch,OCIFetchInto, and OCI FetchStatement. 
The first three correspond fairly straightforwardly to the single-column-, row-, and array-fetching func- 
tions enjoyed by all other PHP database extensions — but the last is unique to Oracle. It fetches the 
entire result set into one big array. This can mean less looping and faster access to your data. Of course, 
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you should make sure that you are returning a reasonably small result set; otherwise, you can bring 
PHP to its knees. 

All caps 

Oracle column names, which become associative array indices, are in all capital letters. You can ask 
for the field in lowercase, but by the time it comes back from the database it will be in all caps, as 
shown in the following code: 

$query = "SELECT product_name , modified, created 
FROM product 
WHERE product_id = 1" ; 
$stmt = OC I Pa rse ( $conn , $query); 
OCIExecute($stmt, OCI_DEFAULT) ; 
$err_array = OC I Er ror ( $stmt ) ; 
if ($err_array) { 

$err_message = $err_array[ 'message '] ; 

$error_str = $err_message ; 

OCI FreeStatement ( $stmt ) ; 

1 else ( 

OC I FetchStatement ( $stmt , $res) 
OC I FreeStatement ( $stmt ) ; 
$product_name = $ res [ ' PRODUCT_NAME ' ] [0] ; 
$modified = $res [ ' MODI FI ED ' ] [0] ; 
$created = $ res [' CREATED '] [0] ; 

} 

Transactionality 

Oracle's famous transactionality implies that all INSERT, UPDATE, and DELETE statements must 
be committed or rolled back before they will really be stored in the database. You can commit 
automatically during the 0CIExecute( ) step, but if you really want an entire string of queries to 
succeed or fail together — the essence of transactionality — it's better to commit by hand when 
all of them are complete. 

$query = "DELETE FROM product 

WHERE product„name = ' $product_name ' " ; 
$stmt = OC I Pa rse ( $conn , $query); 
OCIExecute($stmt, 0CI_DEFAULT) ; 
$err„array = OC I Er ror ( $s tmt ) ; 
if ($err_array) { 

$err ^message = $err_array[ 'message '] ; 

$error_str = $err_message ; 

OC I FreeStatement ( $stmt ) ; 

OCIRollback($conn); 
} else ( 

OCI FreeStatement ( $stmt ) ; 

} 
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$query = "INSERT INTO product ( product_name , modified, created) 

VALUES ( '$product_name' , SYSDATE, SYSDATE)"; 
$stmt = OCI Pa rse ( $conn , $query); 
OCIExecute($stmt, OC I_DEFAU LT ) ; 
$err_array = OC I Error ( $stmt ) ; 
if ($err_array) ( 

$err__message = $err_a rray[ ' message '] ; 

$error_str = $err_message ; 

OCIFreeStatement( $stmt ) ; 

OCIRollback($conr) ; 

exi t ; 
) else { 

OCIFreeStatementdstmt) ; 

1 

OCICommi t( $conn ) ; 



The net effect of this code block will be to ensure that there is only, at most, one row in the database 
for each product name. If either the DELETE or the INSERT fails, the state of the database will not be 
changed. You should never have a situation where you have zero or two rows with the same product 
name. Note the second argument to OCIExecute( ) is OCI_DEFAULT, which means that statements 
will not be auto-committed and must, therefore, be committed by hand. 

O^jsjv" '*' s vei 7 important to remember that commits and rollbacks occur on a connection, not 
on a statement. Everything since the last commit or rollback will be entered into the data- 
base when you call OCICommi t() orOCIRollback(). You may call it as many times during a script 
as you like, but generally all the parts of a transaction are committed or rolled back together. 

Stored procedures and cursors 

Stored procedures are programs that execute on the database. They move some of the program- 
ming into the database layer rather than the PHP layer. PHP merely sends data to the function and 
handles any returned values. 

Because you are connecting to a particular compiled program on the database server, you need to 
establish a more specific kind of connection to the stored procedure. This connection is called a cur- 
sor, and the process of designating variables for use by the stored procedure is called binding to a cursor. 
Basically you are taking a PHP variable and transforming it into a variable on the Oracle side, or creat- 
ing a PHP variable in which to store data returned from Oracle. Cursors must be executed separately 
from ordinary Oracle statements. 

The code block that follows shows a simple example of stored procedure being called from PHP. In 
this case, we are executing the stored procedure named get_categori es ( ) , which takes no inputs 
and returns one output , 0 U T 1 , which we are binding to the PHP variable name $cursorl. 

// Call stored procedure get_categori es 

$request = "begin DEV . get_categori es ( : 0UT1 ) ; end;"; 

$cursorl = OCINewCursor( $conn ) ; 

$stmt = OC I Pa rse ( $conn , Irequest); 

OCIBindByName($stmt, ":0UT1", &$cursorl, -1, 0CI_B_CURS0R) ; 
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OCIExecute($stmt) ; 
OCIExecute($cursorl) ; 
$err_array = OCI Error( $conn ) ; 
if ($err_array) { 

$err_message = $err_array[ 

echo $err_message ; 

OCIFreeCursor($cursorl) ; 

OC I FreeStatement ( $stmt ) ; 

OCILogoff ($conn) ; 

exi t ; 

} 

while ( OC I Fetch I nto ( $cursorl , 
$opt_str .= "<0PTI0N VALUE 
. $cat_array [0] 
. "\">" 

. $cat_array[l] 
. "</0PTI0N>\n" ; 

} 

OCIFreeCursor($cursorl) ; 
OC I FreeStatement ( $stmt ) ; 
OCILogoff ($conn) ; 

It's possible to kick off a stored procedure or Oracle function and walk away, but more often you will be 
waiting for a result. This result will come on one or more cursors. These cursors, and possibly any other 
variables that come back to PHP, need to be created by OCI NewCursor ( ) and bound to PHP variables 
using OCIBi ndByName( ) . They are not immediately available to PHP otherwise. After that, they can be 
treated much like statements — their contents can be fetched, and their memory must be freed. 



Project: Point Editor 

The product point editor is a very simple Oracle tool that allows you to edit the data associated with a 
single item in a product catalog (for instance, for an e-commerce site). Not only does it fetch informa- 
tion that all products share, such as product name and SKU, but it automatically sweeps up variable 
product attribute data for editing. This is data associated with each item, such as price, manufacturer, 
size, color, and so forth; it differs for items depending on what kind of thing they are — cars will have 
a color but not a gender, clothing might have a gender but not a type of transmission. 

Because the attribute information you wish to save for each product varies with the product cat- 
egory — for books you might want to know the author and number of pages, whereas for toys you 
might want to know recommended age — you cannot simply save this information in the product 
table, even if it would normally be one-to-one data. To maintain flexibility, each product category 
(books, toys, and so on) has a number of attributes associated with it, and then each product is 
associated with a number of attribute values. The relationships look schematically like this: 

Category 
category_i d 
category_name 



' message ' ] ; 



&$cat_a rray ) ) 
=\" " 
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Product 
product_i d 
product_name 
category_i d 

Attn bute 
attri bute_i d 
attri bute_name 
category_i d 

Attri bute_val ue 
attri b_val _i d 
attri b_val 
attri bute_i d 

Product_attri bute 
product_i d 
attri b_val _i d 

The product point editor will query the database for all attributes associated with this product and 
construct a series of pull-down menus with all possible attribute values neatly laid out for the editor 
to select from. If an attribute value is already associated with this product, that value will be prese- 
lected in the HTML form field. 

Listing 35-1 is a file of functions that are used in both the product point editor and the product 
batch editor in the next section. This file should be saved under the name oci 8_f uncs . php. 



LISTING 35-1 



Common Oracle functions (oci8_funcs.php) 

<?php 

* Functions for Oracle-based tools * 
putenvC "0RACLE_H0ME=/tool s/oracl e" ) ; 



// Use when fetching data from the db 

function unescape_quotes ( $str ) 

{ 

$esc_str = str_replace( , , $str); 
$esc2_str = str_repl ace ( " \ " \ " " , "\"", $esc_str); 
return $esc2_str; 

} 
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// Use when inserting data into the db 

function escape_sq($str) 

{ 

$esc_str = str„replace( , , $str); 

return $esc_str; 

} 



function escape_html ( $str ) 
{ 

$gt_str = str_repl ace( "&gt ; " , ">;", $str); 
$lt_str = str_repl ace( "&1 t ; " , "<", $gt_str); 
$dq_str = str_repl ace( "&quot ; " , "\"", $lt_str); 
$esc_str = str^repl ace( "&amp ; " , $dq_str); 
return $esc_str; 

} 



// Use this one for INSERTS, UPDATES, and DELETES 
function parse_exec_f ree( $conn , $query, &$error_str) 
{ 

$stmt = OC I Pa rse ( $conn , $query); 
OCIExecutedstmt, OCI_DEFAULT) ; 
$err_array = OC I Er ror ( $ stint ) ; 
if ( $err„array ) { 

$err_message = $er r_a rray[ ' message '] ; 

$$error_str = $err_jnessage ; 

OCIFreeStatement($stmt) ; 

$stmt = FALSE; 
) else ( 

OCIFreeStatement($stmt) ; 

$stmt = TRUE; 

} 

return $stmt; 



// Use this one for SELECTS 

function pa rse_exec_f etch ( $conn , $query, &$error_str, &$res, 

$nul 1 s=0) 

{ 

$stmt = OC I Pa rse ( $conn , $query); 
OCIExecutedstmt, OCI_DEFAULT) ; 
$err_array = OC I Er ror ( $stmt ) ; 
if ($err_array) ( 

$err_message = $err_a rray[ ' message '] ; 

$$error_str = $err_message ; 

OCIFreeStatement($stmt) ; 

$stmt = FALSE; 
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} else { 

if ($nulls == 1) { 

OCIFetchStatement($stmt, $res, OCI_RETURN_NULLS) ; 
} else { 

OC I FetchStatement ( $stmt , $res); 

1 

} 

return $stmt; 



// For batch_upl oad . php , which writes a separate error log 

function choke_and_di e ( $conn , $fp, $error_str) 

{ 

OCIRollback($conn) ; 
OCILogoff ($conn) ; 

$error_line = $er ror_str . " <BR>\n " ; 

echo $error_l i ne ; 

fwrite($fp, $error_l i ne ) ; 

fwrite($fp, "</HTML>\n" ) ; 

f cl ose( $fp) ; 

exit; 

} 



// For all nonl ogwri ti ng uses (which is most of them) 

function di e_si 1 entl y ( $conn , $error_str) 

{ 

OCIRollback($conn) ; 
OCILogoff ($conn) ; 

// You can uncomment these when debugging 
//$error_l i ne = $error_str. "<BR>\n" ; 
//echo $error_line; 
exit; 

} 



// Excel sometimes adds random quotes around field contents 

function unquote($str) 

{ 

$pos = strpos($str, " \ " " ) ; 
if ($pos === 0) ( 

$qstr = substr($str, 1, -1); 

return tn'm( $qstr ) ; 
} else { 

return tri m( $str ) ; 

} 

} 
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// Excel sometimes doubles double-quotes in an attempt to close 
// them 

function stri p_d b ( $ s t r ) 
{ 

$esc_str = str_repl ace ( " \ " \ " " , "\"", $str); 
return $esc_str; 

} 

?> 



Listing 35-2 is the actual product point editor itself. 



LISTING 35-2 



Product point editor (prod_point.php) 

<?php 

/***************************************************** 

* fhis is the product point editor. * 

* fhe purpose of this tool is to edit all the data * 

* associated with a single product. It will mostly * 

* be used for trivial fixes (e.g., spelling errors) * 
***************************************************** i 

i ncl ude ( " oci 8_f uncs . php" ) ; //common functions 
SthisDB = "dev" ; 
SthisDBuser = "oci_user"; 
$thi sDBpassword = "sesame"; 

// 

// EDIT PRODUCT DATA 

// 

if($_P0ST[' submit'] == "Submit") ( 

// Get a timestamp 

$begin_time = time(); 

// Open the pipe 

$conn = OCILogon($thisDBuser, $thi sDBpassword , SthisDB) 
or die("Can't get a database connection."); 

// UPDATE PRODUCT TABLE 

$product_id = $_P0ST[ ' product_i d ' ] ; 

$product„name = escape_sq( $_P0ST[ ' product_name ' ] ) ; 

$sku = escape_sq ( $_P0ST[ ' s ku ' ] ) ; 

$itemurl = escape_sq ( $_P0ST[ ' i temurl ' ] ) ; 

$itemimage = escape_sq ( $_P0ST[ ' i temi mage ' ] ) ; 
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$desc_text = escape_sq ( $_P0ST[ ' desc_text ' ] ) ; 

$query = "UPDATE product 

SET product_name = ' $product_name ' , 
sku = ' $sku ' , 
i temurl = ' $ i temurl ' , 
itemimage = ' $i temi mage ' , 
desc_text = ' $desc_text ' , 
modified = SYSDATE 
WHERE product_id = $product_i d" ; 
$stmt = parse_exec_f ree( $conn , $query, &$error_str ) ; 
if ( !$stmt) { 

di e_si 1 ently ( $conn , $error_str); 

} 

// UPDATE PRODUCT_ATTRI B_VAL TABLE 

// First blow away all existing rows for this product 
$query = "DELETE FROM product_attri b_val 

WHERE product_id = $product_i d" ; 
$ stint = parse_exec_f ree( $conn , $query, &$error_str ) ; 
if ( !$stmt) 1 

di e_si 1 ently ( $conn , $error_str); 

} 

if (is_array($_POST['attrib']) && 
count($_POST['attrib']) > 0) ( 

foreach ( $_P0ST[ ' attri b ' ] as $att ri b_i d=>$a v_i d_a rray ) { 
if ( i s_a rray ( $av_i d_a rray ) && count ( $av_i d_a rray ) > 0) ( 
foreach ( $av_id_array as $attri b_val_i d ) { 
// If attrib value is not Delete All, 
// add new rows 
if ($attrib_val_id != -1) I 
$query = 

"INSERT INTO product_attri b_val 
( attri b_val_i d , product_id, modified, created) 
VALUES($attrib_val_id, $product_i d , 
SYSDATE, SYSDATE)"; 

$stmt = 

pa rse_exec_f ree ( $conn , Iquery, &$error_str ) ; 
if ( !$stmt) 1 

die_silently($conn, $error_str) ; 

) 

1 

} 

} 

1 

} 

OCICommit($conn) ; 
OCILogoff ($conn) ; 
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/* 

// Uncomment this block for debugging 
// Get a second timestamp, and do the math 
$end_ti me = ti me ( ) ; 
echo "DONE! This operation took " 
.($end_time - $begin_time) 
." seconds to complete."; 
exi t ; 
*/ 

// Redisplay the form 

header("Location: $PHP_SELF?url =$prod_url " ) ; 

} 



// 

// SHOW FORM 

// 

elseif (!isSet($_POST['submit']) | 

$_P0ST[ 'submit' ] != "Submit") ( 
set_ti me_l i mi t ( 0 ) ; 
// Get a timestamp 
$begin_time = time(); 
// Open the pipe 

$conn = OC I Logon ( $thi sDBuser , $thi sDBpassword , SthisDB) 
or die("Can't get a database connection."); 

// Get the product data based on a unique URL 
//passed in the GET vars 
$url = $_GET['url ']; 
it ($url == "") { 

// If a URL isn't passed, spit out a message and quit 

echo "<HTML>\n<BODY>" ; 

echo '<P>You need to designate a product to edit by 
passi ng a url 1 i ke this: 
http: //local host/tool s/prod_poi nt . php ' . 
' ?url=book_PHP5_Bible.</P>' ; 

echo "</BODY>\n</HTML>" ; 

exi t ; 

} 

$query = "SELECT product_id, name, sku, itemurl, itemimage, 
desc_text, category_id 
FROM product 
WHERE url = '$url 1 " ; 
$stmt = pa rse_exec„f etch ( $conn , $query, &$error_str, &$res); 
if (!$stmt) ( 

di e_s ilently($conn, $er ror_st r ) ; 
) else ( 

OCI Free Statement ( $stmt ) ; 



590 



An Overview of Oracle 



35 



$product_id = $ res [ ' PR0DUCT_I D 1 ] [0] ; 
$product_name = $ res [ ' PR0DUCT_NAME ' ] [0] ; 
$sku = $res['SKU'][0]; 
$itemurl = $res[ ' ITEMURL ' ][0] ; 
$itemimage = $ res [ ' I T EM I MAG E ' ] [0] ; 
$desc_text = $ res [ ' DESC_TEXT ' ] [0] ; 
$category__id = $ res [ ' CATEG0RY_I D ' ] [0] ; 



// Get attributes for all products in this category 
$query = "SELECT attri bute_i d , attri bute_name 
FROM attribute 

WHERE category_id = $category_i d " ; 
$stmt = pa rse_exec_f etch ( $conn , $query, &$error_str, &$resl); 
if ( !$stmt) { 

di e_si 1 entl y ( $conn , $error_str); 

exit; 
} else { 

0C I FreeStatement ( $stmt ) ; 

} 

if (is_array($resl['ATTRIBUTE_ID']) && 
count($resl[ ' ATTRI BUTE_I D ' ] ) > 0) i 
foreach ($ resl [' ATTRI BUTE_I D ' ] as $ key=>$att r i b_i d ) { 
$attrib_name = $ resl [' ATTRI BUTE_NAME '][$ key ] ; 
// Get attrib values for this product 
$query = "SELECT product„attri b„val . attri b_val_i d 
FROM product_attri b_val , attrib_val 
WHERE product_att ri b_val . attri b_val _i d = 
attri b_val . attri b_val_i d 

AND attri b_val . attri b_i d = $attrib__id 
AND product_attri b_val . product_i d = 

$product„id" ; 

$stmt = parse_exec_fetch($conn , $query, &$error_str, 

&$res2) ; 

if ( !$stmt) ( 

di e_s ilently($conn, $er ror_st r ) ; 
) else { 

OCIFreeStatement($stmt) ; 
// Get all possible attribute values 
//for this attribute 
// and construct nice pulldown lists 
$query = "SELECT att r i b_val _i d , name 
FROM attrib_val 
WHERE attri b_i d = $attrib_id 
ORDER BY name" ; 
$ stint = pa rse_exec_f etch ( $conn , $query, 
&$error_str, &$res3); 

if ( !$stmt) { 
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die_silently($conn, $error_str) ; 
) else ( 

OCIFreeStatement($stmt) ; 

// This stuff is for Case 2 below 

lis^vals = $ res2 [ ' ATTRI B_VAL_I D ' ] ; 

$num_is_vals = count( $i s_val s ) ; 

$poss_vals = $ res3 [ ' ATTRI B_VAL_I D ' ] ; 

$num_poss_val s = count( $poss_val s ) ; 

$nonmatchi ng = array_di f f ( $poss_val s , $is_vals); 

if ( $num_poss_val s > 0) ( 
foreach ($poss_vals as 

$av_key=>$aval ue„i d ) ( 



$av_name = $res3[ ' NAME ' ] [$av_key] ; 
// Existing values are selected in 
/ / this list. 

// Case 0: if no existing value 
// then don't highlight any 
if (! i s_a rr ay ($ i s_va 1 s ) | 



$num_is_vals ==0) ( 
$av_str .= "<0PTI0N 
VALUE=\"$aval ue_id\">$av„name</0PTI0N>\n" ; 

} 

// Case 1: single attrib value 
elseif ( $num_i s_val s ==1) { 

if ($is_vals[0] == $avalue_id) ( 

$av_str .= "<0PTI0N VALUE=\ " $a val ue_i d\ " 



"<0PTI0N VALUE=\"$aval ue_i d\ " >$av_name</OPTI 0N>\n " ; 



1 

} 

// Case 2: multiple attrib values 
// A bit messy because I have to avoid 
// multiple nonmatching options 
elseif ( $num_i s_val s > 1) ( 
foreach ($is_vals as $avid) { 
if ($avid == $avalue_id) { 



$av_array[] = 

"<0PTI0N VALUE=\"$avalue_id\" SELECTED>$av_name</0PTI0N>" ; 



if ($avid == $avalue_id) { 
$av_array[] = 
"<0PTI0N VALUE=\"$aval ue_id\">$av_name</0PTI0N>" ; 
) 



SELECTED>$av_name</OPTION>\n 



) else j 
$av_str 



if ( count ( $nonmatchi ng ) > 0) { 
foreach ( $nonmatchi ng as $avid)( 
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) 

} 

$av_str = impl ode( "\n" , $av_array); 

) 

} 

) 

} 

$attrib_str .= "$attri b_name ( $num_i s_val s ) : <SELECT 
NAME=\"attrib[$attrib_id][]\" 
SIZE=5 MULTI PLE>\n<0PTI0N VALUE= ' - 1 ' >Del ete A1K/0PTI0N> 
\n$av_str</SELECTXBRXBR>\n" ; 

unset ( $a v_a rray ) ; 

unset ( $a v_st r ) ; 

) 

} 

} 

OCILogoff ($conn) ; 



// 

// DISPLAY FORM 

// 

$php_self = $_SERVER[ ' PHP_SELF ' ] ; 

// Superglobals don't work with heredoc 
$form_str = <<< EOFORMSTR 
<HTML> 
<HEAD> 

<TITLE>Product Point Edi tor</TITLE> 
<STY LE> 
<!-- 
.header 
font-si ze : 
text-al i gn : 
. subheader 
font-si ze : 
background : 
--> 

</STYLE> 
</HEAD> 



(font-family: verdana, arial, sans-serif; 
14pt; font-weight: bold; color: #000000; 
left) 

(font-family: verdana, arial, sans-serif; 
12pt; font-weight: bold; color: #000000; 
#ebeefl; text-align: left) 



<B0DY BGC0L0R="#FFFFFF"> 

<P cl ass="header">Product point editor</P> 
<P>The database is <B>$thi sDB</BX/P> 



<PXB>PR0DUCT DATA</BX/P> 

<F0RM ACTI0N="$php__sel f " METH0D="post"> 

<I NPUT TYPE=H I DDEN NAME="product_id" VALU E=" $product_i d " > 
Name: < INPUT TY PE=TEXT NAME="product_name" SI ZE=30 
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VALUE="$product_name"XBRXBR> 

SKU #: <INPUT TYPE=TEXT NAME="sku" SIZE=70 

VALUE="$sku"XBRXBR> 

Item URL: <I NPUT TYPE=TEXT NAME=" i temurl " SIZE=70 
VALUE="$itemurl "><BRXBR> 

Item Image: <INPUT TY PE=TEXT NAME=" i temi mage " SIZE=70 
VALUE="$itemimage"XBRXBR> 

Description: <TEXTAREA NAME="desc_text" C0LS=50 
R0WS=5>$desc_text</TEXTAREAXBRXBR> 

<PXB>ATTRIBUTES</BX/P> 
$attri b_str 

<INPUT TYPEXUBMIT NAME=" submi t" VALUE="Submi t"> 

</F0RM> 

</B0DY> 

</HTML> 

EOFORMSTR; 

echo $form_str; 

// Get a second timestamp, and do the math 

$end_ti me = ti me ( ) ; 

echo "DONE! This operation took ". 

($end_time - $begin_time) 

." seconds to compl ete . <BR>\n " ; 



?> 



For single-product editing, a PHP form that makes a direct connection to the Oracle database is not 
noticeably slower than one that employs a stored procedure. This tool also has the advantage that 
it can be altered by a PHP developer alone, whereas use of a stored procedure usually also requires 
time from a PL/SQL programmer. 



Project: Batch Editor 

To edit data for more than one product at a time, you might want to use stored procedures. This tool 
the product batch editor, has two main parts. A script called header_downl oad . php downloads the 
attributes for a particular category to a spreadsheet. A corresponding script called batch_upl oad_ 
new . php allows the user to upload data from a spreadsheet to the server, where it is loaded into the 
database. This is the simplest use of stored procedures. 

Listing 35-3 is the first stored procedure called in header_downl oad . php. It is called get_ 
categories.sql, and it merely downloads a complete list of all the product categories in this 
schema. 
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LISTING 35-3 



Stored procedure (get_categories.sql) 

CREATE OR REPLACE PROCEDURE get_categori es ( 
category_l i st_out OUT pack . my_ta rgets ) 

IS 

BEGIN 

OPEN category_l ist_out FOR 

SELECT category_i d , category_url 

FROM CATEGORY 

ORDER BY category_url ; 

END; 

/ 

show errors 



After you use the form to select a category, header_downl oad . php calls the stored procedure 
called get_cat_header shown in Listing 35-4. This takes the category ID as an input and returns 
two cursors: one consisting of some common product fields, and the other consisting of attribute 
types associated with this category. 



LISTING 35-4 



A second stored procedure (header_download.php) 

create or replace procedure get_cat_header( 
category_i d_i n INTEGER, 
cat_header_out OUT pack.my_targets , 
cat_attri b_out OUT pack.my_targets , 

IS 

v_action VARCHAR2(2) := '01' ; 
BEGIN 

IF category_i d_i n is NULL THEN 

OPEN cat_header_out for select NULL from DUAL; 

OPEN cat_attrib_out for select NULL from DUAL; 
END IF; 

open cat_header_out for 
SELECT 
col umn_name , 
col umn_di spl ay_name , 
col umn_order 
FROM 

event_tabl e_col umns 
WHERE 

table_name = 'product' 
ORDER BY col umn_order ; 
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open cat_attri b_out for 
SELECT attri bute_i d , attri bute_name 
FROM attribute 

WHERE category_id = category_i d_i n ; 

END; 

/ 

show errors 



Listing 35-5 is header_downl oad . php, which shows the form to call both stored procedures. 



LISTING 35-5 



New product form (header_download.php) 

<?php 

* New product download attributes script. * 

* The purpose of this tool is to download * 

* a spreadsheet with the product data * 

* header. Editors will use this to add * 

* new items to a category. Use script * 

* batch_upl oad_new . php to upload data. * 

i ncl ude ( " oci 8_f uncs . php" ) ; //common functions for Oracle tools 
SthisDB = "dev" ; 
SthisDBuser = "oci_user"; 
$thi sDBpassword = "sesame"; 

// Open the pipe 

$conn = OCILogon($thisDBuser, $thi sDBpassword , SthisDB); 

// 

// GET THE CATEGORY HEADER 

// 

if ($_P0ST[' submit'] == "Add") { 

// Call stored procedure for this category 

$cat_id_in = $_P0ST[ ' cat_i d ' ] ; 

$request = "begin DEV . get_cat_header ( $ca t_i d_i n , 
:0UT1, :0UT2); end;"; 

$cursorl = OC I NewCursor ( $conn ) ; 
$cursor2 = OC I NewCursor ( $conn ) ; 
$stmt = OC I Parse ( $conn , $request); 

OCIBindByName($stmt, ":0UT1", &$cursorl, -1, 0CI_B_CURS0R) ; 
OCIBindByName($stmt, ":0UT2", &$cursor2, -1, 0CI_B_CURS0R) ; 
OCI Execute ( $stmt ) ; 
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OCIExecute($cursorl) ; 
0CIExecute($cursor2) ; 
$err_array = OCI Error ( $conn ) ; 
if ($err_array) ( 

$err_message = $er r_a r ray [' message '] ; 

echo $err_message ; 

OCIFreeCursor($cursorl) ; 

0CIFreeCursor($cursor2) ; 

OC I FreeStatement ( $stmt ) ; 

OCILogoff ($corn) ; 

exit; 

} 

while (OCIFetchInto($cursorl,&$datal)) ( 
$p_array[] = $datal[l]; 

} 

while (0CIFetchInto($cursor2,&$data2) ) { 
$a_array[] = $data2[l] . " | " . $data2[0] ; 

1 

OCIFreeCursordcursorl) ; 

0CIFreeCursor($cursor2) ; 

OCI FreeStatement ($stmt) ; 

OCILogoff ($conn) ; 

// ASSEMBLE THE DOWNLOAD 

$init_p_str = i mpl ode ( " \t " , $p_array); 

$p_str = str_repl ace( "CATEGORY_I D" , $cat_id_in, $ i ni t_p_str ) ; 
if ( count ( $a_a rray ) > 0) ( 

$a_str = impl ode( "\t" , $a_array); 

} 

$full_header = i mpl ode ( " \t " , array ( $p_str , $a_str)); 

// SEND THE FILE 
$header_file = 'header. xls.Z'; 
$zp = gzopen ( $ header_f i 1 e , "w+" ) ; 
gzwrite($zp, $f ul l_header ) ; 
gzcl ose( $f p ) ; 

header(" Location: header. xls.Z"); 

// For IE5.X, this is the correct way to trigger a download 
//--by simply directing the browser to download a file type 
// that the browser cannot open 



// 

// CHOOSE A CATEGORY 

// 

elseif (! i sSet ( $_P0ST[ ' submit ']) ) { 

// Call stored procedure get_categori es 

$request = "begin DEV . get_categori es ( : 0UT1 ) ; end;"; 

$cursorl = OC I NewCursor ( $conn ) ; 

$stmt = OC I Pa rse ( $conn , $request); 
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OCIBindByName($stmt, ":0UT1", &$cursorl, -1, OC I_B_CU RSO R ) ; 
OCI Execute ( $stmt ) ; 
OCIExecute($cursorl) ; 
$err_array = OC I Error ( $conn ) ; 
if ($err_array) ( 

$err_message = $err_array[ 1 message '] ; 

echo $err_message ; 

OCIFreeCursor($cursorl) ; 

OCIFreeStatement($stmt) ; 

OCILogoff ($conn) ; 

exi t ; 

} 

while ( OCI Fetch I nto( $cursorl , &$cat_array ) ) 1 
$opt_str .= "<0PTI0N VALUE=\"" 
. $cat_array [0] . "\">" 
. $cat_array[l] . "</0PTI0N>\n" ; 

} 

OCIFreeCursor($cursorl) ; 
OCIFreeStatement($stmt) ; 
OCILogoff ($conn) ; 



// CHOOSE CATEGORY FORM 

$php_self = $_SERVER[ ' PHP_SELF ' ] ; 

// Superglobals don't work with heredoc 

$form_str = <<< E0F0RMSTR 
<HTML> 
<HEAD> 

<TITLE>Batch Editor New: Downl oad</TITLE> 
<STYLE> 

<!-- 

.header {font-family: verdana, arial, sans-serif 
font-size: 14pt; font-weight: bold; color: #000000; 
text-align: left) 

.subheader (font-family: verdana, arial, sans-serif; 

font-size: 12pt; font-weight: bold; color: #000000; 

background: #ebeef 1 ; text-align: left) 

.ftrnote (font-family: verdana, arial, sans-serif; 

font-size: 8pt; color: #000000; text-align: left) 

LI { 1 1 ne-hei ght : 200% ) 

--> 

</STYLE> 
</HEAD> 

<B0DY BGC0L0R="#FFFFFF"> 

<P cl ass="header">Batch editor new: download</P> 
<P>The database is <B>$thi sDB</BX/P> 
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<F0RM ACTION="$php_self" METH0D="P0ST"> 
<SELECT NAME="cat„id" S I ZE=1> 

<0PTI0N VALUE="-1" SELECTED>Choose one</0PTI0N> 

$opt_str 

</SELECTXBR> 

<INPUT TY P E=SUBM IT NAME="submi t" VALUE="Add"> 

</F0RM> 

</B0DY> 

</HTML> 

EOFORMSTR; 

echo $form_str; 

} 

?> 



The result of header_downl oad.phpisa zipped spreadsheet with one row. It resembles the first 
row of the image in Figure 35-1. 



FIGURE 35-1 
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We have filled in some data in the preceding figure, using the header row as a guide. 

Note that the attributes at the top have names like "Pri ce | 376". The number is the attribute ID, 
which will be used when we upload data with Listing 35-6, batch_upl oad_new . php. This script 
enables the user to upload a spreadsheet to the server, using the normal HTML file upload capabil- 
ity of his browser. The server will then convert the spreadsheet into rows of data, which are inserted 
into the database. 



LISTING 35-6 



Spreadsheet upload script (batch_upload_new.php) 

<?php 

* New product batch upload script. The * 

* purpose of this tool is to upload a * 

* spreadsheet with new product data. * 

* Editors will use this to add new items * 

* to a category. Usescript * 

* header_downl oad . php to get attributes. * 

i ncl ude ( " oci 8_f uncs . php" ) ; //common functions for Oracle tools 
SthisDB = "dev" ; 
SthisDBuser = "oci_user"; 
$thi sDBpassword = "sesame"; 



// HEADER 

$header_str = <<< ENDOFHEADER 

<HTML> 

<HEAD> 

<TITLE>Batch Editor New: Upl oad</TITLE> 
<STYLE> 

<!-- 

.header {font-family: verdana, arial, sans-serif; 
font-size: 14pt; font-weight: bold; color: #000000; 
text-align: left) 

.subheader (font-family: verdana, arial, sans-serif; 
font-size: 12pt; font-weight: bold; color: #000000; 
background: #ebeef 1 ; text-align: left) 

--> 

</STYLE> 
</HEAD> 

<B0DY BGC0L0R="#FFFFFF"> 

<P class=" header ">Batch editor new: upload</P> 
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<P>The database is <B>$thi sDB</BX/P> 

ENDOFHEADER; 

echo $header_str ; 



// ADD NEW PRODUCTS 
if($„POST['submit'] == "Upload") ( 
set_t i me_l i mi t ( 0 ) ; 
echo "<P>Check the error log 

(<A HREFV'upl oad_l og . html \ " >upl oad_l og. html</A>) 
for probl ems .</?>" ; 

// Copy uploaded file to a specific directory 
$tempfile = $ HTT P_P0ST_F I LES[f i 1 e] [tmp_name] ; 
$1 ocal f i 1 e = $HTTP_POST_FI LES[f i 1 e] [name] ; 
if ( !copy($tempfile, "/tmp/$l ocal f i 1 e" ) ) { 

echo "<P>Error writing file to upload directory. 
Quitting. </P>\n" ; 

exit; 

} 

// Start an error log 
$error_log = 'upload_log.html'; 

$fp = f open ( $error_l og , "w+") or die("Can't open error log."); 
fwrite($fp, "<HTML>\n" ) ; 

// Open the pipe 

$conn = OCILogondthisDBuser, $thi sDBpassword , SthisDB) 
or d i e ( " Can't get a database connection."); 

// Get a timestamp 
$begi n_ti me = timet); 

// Read in the data file as an array 
$uarray = f i 1 e ( " /tmp/$l ocal f i 1 e" ) ; 

// Parse the header for cat_id and attributes 

$header = a r ray_shi f t ( $ua rray ) ; 

$harray = expl ode ( " \t " , $header); 

$num_ha = count ( $ha rray ) ; 

$cat_id = $harray[0] ; 

$attri b_array = array(); 

for($i = 6; $i <= ($num_ha - 1); $i++) { 

$a_array = explode("|", $harray[$i ] ) ; 

$attri b„a r ray [ ] = $a_array[l]; 

} 

$num_attribs = count( lattri b_array ) ; 
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$error_str = " " ; 
$res = array ( ) ; 

// Get all the attrib values ard stick them in a 

// multidimensional array 

f oreach ( $attri b_a r ray as $attrib) ( 

$query = "SELECT attri b_val ue_i d , name 
FROM attrib„value 
WHERE attri b_i d = $attrib" ; 

$stmt = 

pa rse_exec_f etch ( $conn , $query, &$error_str, &$res); 
if ( !$stmt) ( 

choke_and_di e ( $conn , $fp, $error_str); 
) else j 

foreach( $res[ ' NAME ' ] as $key => $val ) { 

$ava[$attrib][$val ] = $ res [ ' ATTRI B_VALUE_I D ' ] [$ key ] ; 

1 

OC I FreeStatement ( $ stint ) ; 

) 

1 

reset ( $attri b_a rray ) ; 

// Shove the data down the pipe, 
foreach ($uarray as $valrow) { 

// Get a fresh product id from Oracle 

Iquery = "begin :new_id := newi d (' product ') ; end;"; 

$sth = OC I Pa rse ( $conn , $query); 

OCIBindByName($sth, ":new_id", &$new_id, 200); 

OCIExecute($sth) ; 

if ( !$sth) ( 

choke_and_di e( $conn , $fp, $error_str); 
) else { 

$ row id = $new_id; 
OC I FreeStatement ( $sth ) ; 

} 

// Format new product data. 
$val_array = expl ode ( " \t " , $valrow); 
$prod_name = unquote( $val_array [1] ) ; 
$prod_name = stri p_db( $prod_name) ; 
$prod_name = escape_sq ( $prod_name ) ; 
echo "Working on $prod_name<BR>\n" ; 
$sku = unquote( $val_array[2] ) ; 
litemurl = unquote( $val_array[3] ) ; 
litemimage = unquote( $val_array [4] ) ; 
$desc = unquote ( $val _a rray [ 5] ) ; 
$desc = escape_sq ( $desc ) ; 

// PRODUCT 

$query = "INSERT INTO product ( 
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product_i d , name, sku, itemurl, itemimage, 
desc, created, modified, category_id) 
VALUES ( 

Irowid, ' $prod_name ' , '$sku', ' $i temurl ' , 
1 Sitemimage' , '$desc', SYSDATE, SYSDATE, 
$cat_id) " ; 

$ strut = pa rse_exec_f ree ( $conn , $query, &$error_str) ; 
if (!$stmt) { 

choke_and_di e ( $conn , $fp, $error_str); 

} 

// PRODUCT_ATTRI B_VALUE 

for ($i = 6; $i <= (6 + $num_attribs - 1); $i++) ( 
$av = unquote( $val_array[$i ] ) ; 
if($av != "") { 

$temp_q = explode("|", $av); 
f oreach ( $temp_q as $av) ( 
$av = unasterisk(lav); 
$av = escape_sq( $av ) ; 
$akey = $i - 6; 

$attrib_id = lattri b_array [$akey] ; 
i f ( $ava [$attri b_i d] [$av] ) { 
$pav = $a va [ $a tt ri b_i d] [$av] ; 
Iquery = "INSERT INTO product_attri b_val ue ( 

attri b_val ue_i d , product_id, created, 

modi f i ed ) 

VALUES( 

$pav, $rowid, SYSDATE, SYSDATE)"; 

$stmt = 

pa rse_exec_f ree ( $conn , $query, &$error_str) ; 
if ( !$stmt) { 

choke_and_di e ( $conn , $fp, $error_str); 

) 

} 

} 

) else ( 

//echo "Null attrib va 1 ue . <BR>\n " ; 




// Get a second timestamp, and do the math 

$end_time = time( ) ; 

echo "DONE! This operation took " 

.($end_time - $begin_time) 

." seconds to complete."; 

OC I Commi t ( $conn ) ; 
OCILogoff ($conn) ; 
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fwrite($fp, "</HTML>\n" ) ; 
fclose($fp) ; 

} 



// SHOW FILE UPLOAD FORM 

elseif ($_P0ST[ 'submit' ] != "Upload") { 

$upload_str = <<< ENDOFUPLOAD 
<P>Upload new product data:</P> 
<F0RM ACTION="$PHP_SELF" METHOD="post" 
ENCTYPE="mul ti pa rt/f orm-data " > 

<INPUT TYPE=HIDDEN NAME="max_f i 1 e_si ze" VALUE="1000000"> 

<INPUT TY P E= F I LE NAM E= " f i 1 e" SIZE=50XBRXBR> 

<INPUT TYPE=SUBMIT NAME=" submi t" VALUE="Upl oad"> 

</F0RM> 

ENDOFUPLOAD; 

echo $upload_str; 

} 

?> 

</B0DY> 
</HTML> 



Notice particularly in this script how we call for a new product ID using Oracle's incrementor 
(search for the comment / / Get a fresh product i d from Oracl e). This is in marked contrast to, 
for instance, MySQL, where the auto -incrementor is generally built into a column's definition and 
can be kicked off by merely entering a null value in that column. 



Summary 

Oracle is one of the biggest names in enterprise databases. The PHP OCI8 extension is quite fast and 
powerful, offering some functionality not found in most other database extensions. However, the use 
of Oracle has many implications and should not be undertaken lightly. 

There are significant differences between the syntax of Oracle functions and those of lighter-weight 
databases. These differences include so-called Sybase-style string escaping, separate parsing and 
execution steps, manual memory management, cursors, transactionality, and the capability to fetch 
data sets into one big array. We demonstrated the use of all these Oracle features in two examples: a 
single-product data editor and a mass data entry tool. 
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When coding PHP, you may sometimes find that you want a data- 
base that's both easy to use and lightweight, without having 
the complexity of a larger RDBMS like MySQL or Oracle. Small 
applications, written for one-off solutions, lend themselves to these types of 
databases, as do applications that just need a powerful query functionality. 
Enter SQLite. SQLite is a lightweight database system that's bundled with 
PHP by default. As you'll see in this chapter, SQLite is a lightweight data- 
base system appropriate for many uses in PHP (and other languages, too). 



IN THIS CHAPTER 



An introduction to SQLite 
Using SQLite-related functions 



An Introduction to SQLite 

SQLite is a database engine that operates without the use of a database 
server. You may find yourself reading that sentence again, but it's true. 
SQLite has no server component, but rather directly interacts with its 
data through files or directly in memory. SQLite works well with small (to 
medium) data sets or in low-volume transactions, but because the stor- 
age medium is usually disk, accessing the data can be slower than a more 
robust and traditional RDBMS like MySQL. 

SQLite doesn't have a privilege system in the way that MySQL does. This 
means that it isn't possible to limit who has access to certain databases or 
tables within a given database. The files holding data in SQLite are typi- 
cally owned and readable by the user under which the web server is run- 
ning. With these issues in mind, it's not appropriate to use SQLite to store 
sensitive data. 

This chapter gives a brief introduction to the most basic usage of SQLite. More 
information can be found in the online manual at www. php.net/sql ite. 
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Using SQLite-related Functions 

SQLite is simple to use. So much so that working with SQLite may confuse those readers who are 
accustomed to some level of complexity when working with databases. 

Creating Databases 

SQLite databases are created simply by calling the sql i te„open ( ) function, like this: 

$ s q 1 d b = sql i te_open ( "mydatabase . sql i te" ) ; 
Alternately, an object-oriented interface is also available to create new databases: 

$ s q 1 d b = new SQLi teDatabase( "mydatabase . sql i te" ) ; 

You will concentrate on the object-oriented interface to SQLite in this chapter. More information on 
the functional interface can be found in the online PHP manual for SQLite at http://us2.php. 
net/sql ite. 

Running Queries 

In the realm of SQLite, queries, including most interactions with the database such as SELECT, 
INSERT, UPDATE, and DELETE operations, take place through the query ( ) method. For example: 

$sql db->query( "SELECT * FROM foo"); 

This section examines the query ( ) method as it is used to create tables and insert, and retrieve data. 

SQLite also has a method called exec ( ) , which can be used for statements that return no results, 
such as statements that create tables and the like. Examining SQLite code "in the wild," it's much 
more common to see the query ( ) method used, for better or worse, than it is to see exec ( ) ; there- 
fore, it's q u e ry ( ) that you'll concentrate on in this section. 

Creating Tables 

SQLite stores its data as strings regardless of the type specified in the table creation statement. This 
means that SQLite can be slow when sorting data. 

Automatically incremented columns, like those frequently used for identifier columns, are created 
by SQLite without need for an additional keyword such as a u t o_i n c r eme n t , simply by specifying 
that an integer column is the primary key. 

Here's an example that creates a table to store the geopolitical states of the union in the United 
States. In this example, it is assumed that the $ sql db handle has been created. 

$ s q 1 db->query( "CREATE TABLE mytable (id integer primary key, stateabb 
char(2) , state char(50) )"); 
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Table creation need only take place once. Attempting to create a table that already exists causes a 
PHP warning, like the one shown in Figure 36-1. 



FIGURE 36-1 



Attempting to create a table that already exists results in a warning 



FjrcfoK 



JS|x| 



Fie E* View Hqjtay femkiarta loofc Help 

C X ,Ai J J) | http://php6.bri«igla.ota/sqlite/s<#te.!*ip 




Therefore, it's up to you either to ignore the warning or comment out code that creates tables if they 
already exist. One method for ignoring the error (though we definitely do not recommend ignoring 
errors) would be to precede the call to the queryO method with an "at" sign, @. 

@$sql db->query( "CREATE TABLE mytable (id integer primary key, stateabb 
char(2), state char(50))"); 

Another method available in newer versions of SQLite is to use the 'if not exists' syntax 
when creating a table. Using 'if not exi sts ' tells SQLite to create the table only if the table isn't 
already there. It is preferred to use this syntax rather than ignoring the error using the @ method 
shown previously. 
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Inserting Data 

Like other statements, inserting data into an SQLite database is also accomplished using the 

q u e ry ( ) method. Going back to the example table created in the last section, you could insert some 

states and their respective abbreviation with these statements: 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
('WI', 'Wisconsin')"); 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
( ' CA' , ' Calif orni a ' ) " ) ; 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
CIL',' Illinois')"); 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
( 'OR' , 'Oregon ' )") ; 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
( ' MN ' , ' Mi nnesota ' ) " ) ; 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
( ' AL ' , ' Al abama ' ) " ) ; 

$sqldb->query("INSERT INTO mytable ( stateabb , state ) VALUES 
( ' WA ' , ' Washi ngton ' ) " ) ; 



Whenever you're working with input from the web, as you frequently are in PHP, it's critical to make 
sure that the data has been checked to ensure that it contains valid and acceptable values. For SQLite, 
this means using the s q 1 it e_e scape_string( ) function on any input from outside of your program, 
such as $_P0ST and $_GET, but also from cookies or even server and environment variables in a shared 
hosting environment. 

Assume that you're accepting a POST from a web form containing the elements username and pass- 
word. This code would take those input values and make them safe to use in SQLite statements: 

$safe_user = sql i te_escape_stri ng ( $_P0ST[ ' username ']) ; 
$safe_pass = sql i te_escape_stri ng ( $_P0ST[ ' password ']) ; 

Now instead of using $„P0ST[ ' username' ] within your SQL statement, you would use $saf e_ 
user instead. 



Fetching Data 

While there are several means by which data can be retrieved from SQLite tables, the simplest 
method for retrieving data from SQLite is accomplished by using the f etch ( ) method. The 
f etch ( ) method is an alias for sql i te_f etch_a r ray, which means that data retrieved by this 
method will be placed into an array. 

Going back to the state example from earlier, the data could be retrieved simply with the following 
statement: 

$result = $sql db->query( "SELECT * from mytable"); 
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Then the result is iterated by looping through the result set with the f etch ( ) method. 

while ($row = $resul t->f etch ( ) ) { 
pri nt_r( $row) ; 

1 

The output from this is shown in Figure 36-2, again assuming the inserts from earlier were executed 
in order to insert some sample data. 



FIGURE 36-2 



Printing data from an SQLite table using the fetch() method 
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Array ( [0] ==■ 1 [id] =» 1 [!]=> WI [stateabb] => WI [2] => Wisconsin [state] => Wisconsin ) Array ( [0) => 2 [id] => 2 [ 1] 
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Washington [state] => Washington ) 
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Another method for retrieval of data from SQLite is the f etchAl 1 ( ) method. Fetcha 1 1 ( ) differs 
from f etch ( ) in that with f etchAl 1 (), all data is brought back immediately. This is appropriate 
for smaller data sets where you want to grab everything and then work with it as necessary in your 
program. The implication of fetching an entire data set, if that data set is large, is that it may con- 
sume unnecessary resources versus simply looping through the results with f etch ( ) . The f etch - 
Al 1 ( ) method retrieves data as an array of arrays. 

Other methods also exist for retrieving data from SQLite. These additional methods won't be cov- 
ered here but you can find them online at www .php.net/sql i t e , 
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More on SQLite 

You may find that you'll never encounter a need for SQLite in your PHP projects, especially with the 
ubiquity and ease of use of MySQL. If you do, however, there is much more to SQLite than we've 
covered here, in a book on PHP and MySQL. If you're going to use SQLite, please visit the SQLite 
section of the PHP manual for more information, www.php.net/sql ite. 



Summary 

This chapter gave a brief overview of SQLite and its basic usage in PHP. We looked at creation of 
databases in SQLite using PHP, how to create a table, insert data, and how to select data from that 
table. SQLite isn't appropriate for all usages of database systems, however. For example, SQLite 
doesn't contain a privilege system, so anyone that has access to the file containing your data has 
access to all of the data. 

More information on SQLite and PHP can be found in the online manual at www.php.net/ 
sql i te. 
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Sending E-Mail with PHP 



This chapter is all about using PHP (and, in some cases, databases) to 
send e-mail. If you're looking to receive e-mail with PHP, by using a 
protocol such as POP3 or IMAP, please refer to the PHP manual for 
those functions. 



Sending E-Mail with PHP 

Sending mail is where PHP really comes into its own. But before you can send 
any mail from your server, you need to tweak the configuration file a little. 

Windows configuration 

In Windows, you need to set two variables in the p h p . i n i file: 

■ SMTP: A string containing the DNS name or IP address of an 
SMTP server that relays for the Windows machine on which PHP 
is installed. If it is on the PHP server, specify 1 oca 1 host. 

■ sendmail_from:A string containing the e-mail address of your 
default PHP mail sender (for example, ma i 1 bot@exampl e . com). 



IIS4+ has an SMTP server built in, which is lighter than 
Exchange Server, if you don't need the power of the latter. 



IN THIS CHAPTER 



Sending e-mail with PHP 
Sending e-mail from a form 
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Linux configuration 

You need to check and possibly change one variable in the p h p . i n i file if you're using Unix: 
sendmai l_path, a string containing the full path to your sendmail program (usually /usr/ 
sbin/sendmail or / us r /I i b/sendma i 1 ), a replacement, or a wrapper (such as/var/qmail/ 
bi n /sendma i 1 ). 

The mail function 

The mail ( ) function is the primary function used to send mail with PHP. This function, which 
returns a Boolean, attempts to send one message using the data within the parentheses. The simplest 
use of this function (keeping in mind that this is a dummy address and should not be used for test- 
ing purposes) is: 

<?php 

ma i 1 ( ' recei ver@exampl e . com ' , 'A Sample Subject Line', 
"Body of e-mai 1 \r\nwi th lines separated by the newline 
character . " ) ; 
?> 

This is the default and minimum format: address of recipient, subject line, and body. In this case, 
PHP will automatically add a From : me@sendhost line to each message header. 

You can also, as always, use variables instead of hardcoded values: 

<?php 

Saddress = 'santa@example.com'; 

Isubject = 'All I want for Christmas'; 

$body = "Is my two front teeth . \r\nSi ncerely , Joey"; 

Smailsend = mai 1 ( Saddress , Ssubject, $body); 

echo Smailsend; 

?> 

Multiple recipients all go into the address field, with commas separating them (this feature is not 
supported by all MTAs; if you want to be sure, use cc : instead): 

<?php 

Saddressl = ' recei ver@recei pthost ' ; 
$address2 = 'jane@example.com'; 
$address3 = 'john@example.org'; 

$al l_addresses = "Saddressl, $address2, $address3"; 
$subject = 'A Sample Subject Line'; 

$body = "Body of e-mai 1 \r\nwi th lines separated by the 
newl i ne character . " ; 

Smailsend = mai 1 ( Saddresses , Isubject, $body); 

echo Smailsend; 

?> 
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Remember to ensure that the multiple addresses are one string, as in the preceding code lines. You 
do not want to do this: 

<?php 

$addressl = ' recei ver@recei pthost ' ; 
$address2 = 'jane@example.com'; 
$address3 = 'john@example.org'; 
$subject = 'A Sample Subject Line'; 

$body = "Body of e-mai 1 \r\nwi th lines separated by the newline 
character."; 

// This is wrong, don't do it! 

$mailsend = mai 1 ( Saddressl , $address2, $address3, $subject, 
$body ) ; 

echo $mailsend; 
?> 

Most people would like more control over the addresses, appearance, and format of their e-mails. 
You can do that by putting an additional header after the three default headers. 

<?php 

$address = ' recei ver@recei pthost ' ; 
$subject = 'A Sample Subject Line'; 

$body = "Body of e-mai 1 \r\nwi th lines separated by the newline 
character."; 

$extra_header_str = "From: me@sendhost\n\nbcc : 
phb@sendhost\r\nContent-type: text/pl ai n\ r\nX -ma i 1 er : PHP/" 
. phpversionO; 

$mailsend = mai 1 ( Saddress , Isubject, $body, $extra_header_str ) ; 

echo $mailsend; 

?> 

This "additional header" field is somewhat odd because it crams in several types of information that 
would normally be given their own fields. Ours is not to wonder why; ours is but to explain the 
kinds of things you might want to put in this field. 

■ Your name 

■ The To: address 

■ Your e-mail address 

■ A reply-to or bounce-to address 

■ X-mailer and version number 

■ MIME version 

■ Content-type 

■ Charset (which uses a = to assign a value and not a : like the other headers) 
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Content-transfer-encoding 

Carbon-Copy (cc:) and blind carboncopy (bcc:) recipients 

The mail ( ) function returns 1 (TRU E) when PHP believes it has successfully sent mail. 
This has no relationship to any mail actually being sent or received. There are still an 
endless number of things that can go wrong: bad e-mail address, SMTP daemon incorrectly designated 
or configured, local Internet conditions, and so on. Think of 1 as a message meaning no more than 
"PHP has applied the function to the inputs successfully." 



Sending Mail from a Form 

Sending mail from a form is quite likely the single most popular application of PHP's ma i 1 ( ) func- 
tion. It's a far more functional alternative than HTML's ma i 1 to link tag, which of course results in 
e-mail being sent from the client machine's mail program. 

Listing 37-1 is a simple example form of the type that often sends e-mail. 



LISTING 37-1 



e-mail form (titlehelp.html) 

<html > 
<head> 

<titl e > t i 1 1 ehelp.htmK/titl e> 
</head> 

<body> 
<center> 

<table width="550"> 

<tr bgcolor= #FF9933Xtd al i gn = "center"XBR> 
<H3>The Thriller <BR> 

"What was the name of that thri 1 1 er? "<BR> 

Form</H3X/tdX/tr> 

<tr><td> 

Did you once read an unforgettable thriller, but now you can't 
remember the name? Fill out as many of the fields below as you 
can, press the button to submit, and we'll search our sources 
and e-mail you back. 
</tdX/trX/tabl e> 
</ center> 

<F0RM METHOD=post ACTI0N=" t i tl ehel p . php" > 

<P>First name: <input type="text" size=30 name=" Fi rstName"> 
<P>Last name: <input type="text" size=30 name=" LastName"> 
<P>Your Email Address: <input type="text" size=30 name="Emai 1 "> 
< P> I n approximately what year did the action of the book occur? 
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37 



<input type="text" size=4 name="Year"> 

<P>Can you remember any settings from the book? 

<input type="text" size=30 name="Setti ng"> 

<P>The gender of the protagoni st ( s ) was: <br> 
<ul > 



<i 


nput 


TYPE= 


'radio" 


NAME= 


"Gender" 


VALUE= 


l>Femal e<br> 


<i 


nput 


TYPE= 


'radio" 


NAME= 


"Gender" 


VALUE= 


2>Mal e<br> 


<i 


nput 


TYPE= 


'radio" 


NAME= 


"Gender" 


VALUE= 


3>0ne of each<br> 


<i 


nput 


TYPE= 


'radio" 


NAME= 


"Gender" 


VALUE= 


4>Two males<br> 


<i 


nput 


TYPE= 


'radio" 


NAME= 


"Gender" 


VALUE= 


5>Two females<br> 



</ul > 

<P>When the book first came out, it was: <br> 
<ul > 

<input TYPE="radio" NAME="Status" VALUE=1>A bestsel 1 er<br> 
<input TYPE="radio" NAME="Status" VALUE=2>A critic's darling<br> 
<input TYPE="radio" NAME="Status" VALU E=3>Nei ther<br> 
<input TYPE="radio" NAME="Status" VALU E=4> I don't know<br> 
</ul > 

<P>Please tell us anything else you can remember about this 
title (plot, characters, settings, cover, movie versions, 
etc . ) : 

<br><textarea NAME="Other" R0WS=6 C0LS=50X/texta rea> 
<PXinput type="submit" name="Submi t"> 
</body> 
</html > 



Listing 37-1 submits to a form handler, shown in Listing 37-2. 



LISTING 37-2 



E-mail form handler (titlehelp.php) 

<html ><head> 

<ti tl e>titl ehel p.php</ti tl e> 
</head> 

<body> 
<?php 

// If you wished, you could also save this information to 
// a database 

$LastName = $^P0ST[ ' LastName ' ] ; 
$FirstName = $_P0ST[ ' Fi rstName ' ] ; 
$Year = $_P0ST[ ' Year ' ] ; 
$Setting = $„P0ST[ ' Setti ng ' ] ; 
$Gender = $_P0ST[ ' Gender '] ; 
$Status = $_P0ST[ ' Status '] ; 
$0ther = $_P0ST[ 'Other' ] ; 
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$formsent = ma i 1 ( ' hel p@exampl e . com ' , 

'What was the name of that thriller?', 
"Request from: $LastName $Fi rstName\r\n 

Year: $Year\r\n 

Setting(s): $Setting\r\n 

Protagonist gender: $Gender\r\n 

Book status: $Status\r\n 

Other identifying characteristics: $0ther", 
"From: help@example.com"); 

if ($formsent) { 

echo " < P > H i , $FirstName. We have received your request for 
help, and will try to respond within 24 hours. Thanks for 
visiting!"; 
1 else ( 

echo "I'm sorry, there's a problem with your form. Please try 
again. " ; 

} 

?> 

</body> 
</html > 



There are security implications for using any $_POST variables when sending mail. Spammers 
may use this form for sending spam. A spammer would be able to craft a message into the value of 
$ Fi rstName and have it sent out. One solution is to validate the input and accept only single words 
for first names and then only of a certain length. 



Summary 

E-mail is one of the most useful and attractive functions of the Internet. PHP gives you the ability to 
both send and receive e-mail from a web page. One of the most common uses of PHP's mail func- 
tion is to send an e-mail (often to yourself) with values generated from a Web form. 



618 




33 



Integrating PHP and Java 



The relationship between PHP and Java has changed significantly 
with each new release. Unsurprisingly, given the source code, PHP 
initially had much more in common with C. PHP4 supported inte- 
gration of PHP and Java using a Java servlet environment or, more experi- 
mentally, directly into PHP. Finally, with the overhaul of the object model 
in PHP5, there was a distinctly Java feel to the PHP approach to object- 
oriented programming. Java users will find the improved object model in 
PHP6 very familiar, although there are important differences. 

Given these changes, as PHP takes on a more Java-like cast, there are two 
possibilities for which a discussion of PHP and Java might be pertinent. You 
might need to work on a project that requires PHP and Java or Java Server 
Pages (JSP) to work in tandem. Or you may be approaching PHP from a 
Java background and want to know about the similarities and differences in 
order to learn PHP faster. We will deal with both needs in this chapter. 

If you don't have a need to use Java, or aren't already familiar with the lan- 
guage, this chapter won't do much for you. 



IN THIS CHAPTER 



PHP for Java programmers 
Java Server Pages (JSP) and PHP 
Integrating Java and PHP 
The Java extension 
The Java object in PHP 
Error handling and reporting 



PHP for Java programmers 

Most projects won't require integration of Java and PHP, unless there is 
some specific need due to preexisting architecture. The Java programmer 
approaching PHP for the first time may still want to know more about how 
PHP compares to Java for the purposes of learning PHP scripting. 
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Similarities 

In this section, we discuss some ways in which PHP and Java are similar. 

Syntax 

Though PHP syntax is much closer to C, many conventions used in Java apply to PHP as well. Code 
is whitespace-insensitive, statements are terminated with semicolons, function calls have a similar 
structure (my_functi on ( expressi onl , express i on2 )), and curly braces ({ and ))make state- 
ments into blocks. PHP supports C and C++-style comments (/* */ as well as / /), which are also 
used in Java. 

Operators 

The assignment operators (=, +=, *=, and so on), the Boolean operators (&&, | | , !), and the basic 
arithmetic operators (+, -,*,/, %) all behave as they do in Java. Other operators are similar, with 
some syntax differences. The string concatenation operator, for example, in PHP is a period (. ) 
rather than a plus sign (+) as in Java. 

Object model 

The Java programmers coming to PHP with version 5 can rejoice! You no longer need to unlearn 
your approach to OOP in order to deal with the often crude OOP support in PHP4 and earlier ver- 
sions. The PHP5 addition of keywords (such as private, protected, and publ i c) for dealing with 
member variables should prove familiar to Java coders. New error-handling methods, including the 
built-in Excepti on class, will also be familiar to Java programmers. 

[ ^'1^ Cj£i~£>- J I J f*P ^' la P ter ^ ' or muc ' 1 mol "e detailed information about PHP's object model. 

Memory management 

Under normal circumstances, PHP's garbage-collected environment ensures that you do not need to 
explicitly free allocated memory. If you're used to Java's mostly automated garbage-collected heap, 
you'll be right at home here. 

Packages and libraries 

Many web-specific libraries are built into PHP and are available by default or with minor changes. 
This works similarly to the standard Java packages that are available through JAR files and 
CLASSPATH references. 

Differences 

Although many of the features of PHP have a Java-like feel, there are plenty of notable exceptions 
to the way Java and PHP operate. As a general rule, never assume that a Java feature or concept will 
carry over completely into PHP. 
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Compiled versus scripting 

Unlike Java, PHP is a scripting language. The development cycle is edit-execute rather than edit-com- 
pile-execute, as in Java. PHP code is automatically compiled at execution time and does not produce 
native standalone executables. As a result, the developer is not subjected to rigorous compile-time 
error checking as in Java; many of the errors that you are used to seeing at compile time will not rear 
their ugly heads until the code is executed in PHP. 

Variable declaration and loose typing 

Get used to that leading $. Unlike in Java, all variables in PHP must begin with a $. Variables need 
not be declared before use, nor cast to a different type as in Java. Rather than the Java code: 

String preamble = new StringO; 
Preamble = "We, the people..."; 

or: 

String preamble = "We, the people..."; 

the corresponding PHP code would be simply: 

$preamble = "We, the people..."; 

PHP utilizes dynamic typing; the variable has no intrinsic type and can change with each new state- 
ment. While the following code is perfectly legal in PHP: 

$type = 11 ; 
$type = "11" ; 

you would need to use separate variables in Java, or attempt to recast the variable as a Stri ng, with 
potential problems and a resultant performance hit. 

Variables can be declared and typed as in Java, but this is not required in PHP. 

Java Server Pages and PHP 

PHP can fulfill many functions similarly to Java Server Pages (JSP). The JSP servlet engine serves as a 
scripting language for use with Java, and, just like PHP, is often used in frontend applications. 

Embedded HTML 

PHP is more similar to JSP than Java itself in that you are allowed to write HTML directly rather 
than using endless print statements. Unlike Java, but like JSP, variables can also be referenced from 
within a block of HTML. A simple HTML page using JSP script might look like this: 

<% 

String greeting = "Hello, world"; 

%> 
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<HTML> 
<HEAD> 

<TITLE>Fun with JSP</TITLE> 
</HEAD> 
<B0DY> 

<H1><%= greeting %></Hl> 

</B0DY> 

</HTML> 

Similarly, using PHP, you can write: 
<?php 

$greeting = "Hello, World"; 

?> 

<HTML> 
<HEAD> 

<TITLE>Fun with PHP</TITLE> 
</HEAD> 
<B0DY> 

<HlX?php echo $greeting ?></Hl> 

</B0DY> 

</HTML> 

Pages can freely alternate between HTML and JSP, just as when you use HTML and PHP 

Choose your scripting language 

PHP can actually be used with Java in lieu of JSP, although support is much less robust and subject 
to change in future releases. Many of the shortcuts available to JSP are not available through PHP. For 
example, many of the standard Java class packages are automatically available as in Java Server Pages 
but must be implicitly referenced using PHP Java support. 

~~™ ' i"; ' Don't let new syntax and structure similarities lull you into believing that PHP is truly like 

Java. The forgiving nature of PHP and the loose treatment of variable typing mean that 
code must be treated very differently. Those errors that Java demanded you to fix before it would com- 
pile may not show up in PHP until they are in an end user's browser! 



Integrating PHP and Java 

In the course of your development work, you may run across a situation in which you will be 
required to use PHP and Java together, or this combination may prove advantageous for some 
reason. You basically have two options to accomplish this tricky undertaking, which are outlined 
below. Java environments are inherently complicated and vary according to servlet engine and 
server. Since these issues are well beyond the scope of this book, in all further discussions we will 
assume that you already have a working web server that supports servlets, an installed Java virtual 
machine (JVM), and a working familiarity with Java. 
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The Java SAPI 

The most stable solution is to integrate PHP into a Java servlet environment using the Java Service 
Access Point Identifier (SAPI). This allows the PHP processor to run as a servlet and builds on the 
PHP Java extension (described following). The servlet will run from within a Java servlet engine, 
such as Apache Tomcat. 



Installation and setup 

As with the Java extension, SAPI module support is not built into PHP by default. You will need to 
rebuild PHP with the necessary options ( — with-servlet -with java)as well as any options you 
may require for other uses. (See Chapter 3 for more information on building and installing PHP.) In 
your environment variables, make sure that servlet. jar is included in your C LASS PATH, and add 
the PHP directory containing the 1 ibphp6.so file to LD_LI BRARY_PATH. 

Windows users will need to build the php_java.dll file and copy it into their extersion_dir 
directory and enable the extension in the p h p . i n i file. Also be sure that servlet. jar is included 
in your CLASSPATH, and add the PHP directory containing the PHP DLL files to PATH. 

Building the module will also create a JAR file called phpsrvlt.jar, which must also be included in 
your CLASSPATH. Additional setup specific to your servlet engine will probably be required. Check 
the PHP web site and mailing lists for comments from other users who have successfully configured 
your Java servlet engine for use with this module. 

Further information 

Once you have the module up and running, you should be able to view PHP files normally. Point to 
an existing PHP page, or create a test by printing phpi nf o ( ) to see if you have succeeded. 

Usage of this module is still considered experimental, and there isn't a lot of documentation. You 
probably won't build or use this module unless you already have a specific need for it. As the mod- 
ule is under constant revision, additional useful notes may be found in the README file and other 
sources located in your PHP directory under / sapi/servlet. Users also sometimes add comments 
to the User Contributed Notes in the online manual, so it's probably a good idea to check there every 
so often. Official notes on Java/PHP integration can be found on the PHP web site at www .php.net/ 
manual/en/ref.java.php. 



The Java extension 

If you're feeling particularly adventurous, you can build Java support directly into PHP, using the 
experimental Java extension. Once enabled, the extension allows you to create and call Java objects 
and methods from within PHP. The advantages are obvious to those familiar with Java, but use of 
this extension is not without some pain upfront and the need for some serious care on your part. 



CAUTION 



The Java extension for PHP is subject to continuing revision as it is fine-tuned for future 
versions. Committing to the use of this feature in your application implies added diligence 
to avoid future code breakage. It's not labeled EXPERIMENTAL in the PHP manual for nothing! 
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Installation and setup 

Use of the Java extension will require some modifications to your PHP installation and environment. 
Before rebuilding PHP, it's a good idea to make sure that you have access to pertinent information on 
your Java Development Kit (JDK) environment. Make sure that you know the following information: 

■ The base directory of your JDK installation (typically / usr/java/j2sdk<version> in 
Linux) 

■ The JAVA_H0ME and CLASSPATH environment variables (JAVA_H0ME should be set to the 
above directory) 

■ Location of the Java library (typically in JAVA__HOME/jre/l ib/i386 on Linux) 

Java support is not enabled by default, and you will need to rebuild PHP in order to take advantage 
of its features. During the installation, you must specify the option -with-java=(base direc- 
tory) in addition to any other options you may require. (See Chapter 3 for more information on 
building and installing PHP.) 

Modifications are also required to the php . i ni configuration file in order to enable the exten- 
sion. Open your p h p . i n i file in your favorite editor and search for the [Java] subheading under 
Module Settings. Here's where the information you collected earlier will come in handy. A typical 
modification on a Linux server might look something like this: 

[Java] 

java.home = /us r/ j a va/ j 2sdkl . 4 . 0 

java. library = / us r/ j a va/ j 2sdkl . 4 . 0/ j re/1 i b/i 386/1 i b j a va . so 
java.l i bra ry . path = /usr/1 ib/php/extensions/no-debug-non-zts- 
20020429 

extensi on_di r = /usr/1 i b/php/extensi ons/no-debug-non-zts- 
20020429 

extension = li bphp_j a va . so 
Windows users should also add the following line under Wi ndows Extensi ons: 
extensi on=php_j ava . dl 1 



l |ust to add some confusion for fun, note that the java.l i bra ry variable pertains to 
"' the )ava installation, while java . 1 i brary . path refers to the PHP extension directory 
where the optional PHP support files reside. Most problems with getting the (ava extension to work 
seem to revolve around successfully editing p h p . i n i . 



Remember that these variables must correspond to the settings on your particular server, 
i r- 1 ' "- - | " Windows users must be sure to enclose the path names in quotation marks. 

If all goes well, you should be ready to try calling a Java method from within PHP! 
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A simple invocation ofjava.lang.Systemina JSP environment would look something like this: 

<% 

String version = System . getProperty ( "j a va . vers i on ") ; 
String os = System. getProperty ( "os . name" ) ; 

%> 

<HTML> 
<HEAD> 

<TITLE> Fun with Java and JSP</TITLE> 
</HEAD> 
<B0DY> 

<H3>We are running Java version <%= version %> on the 

<%= os %> platform, and it's worki ng ! </H3> 
</B0DY> 
</HTML> 

Similar code using PHP would, by necessity, be a bit more involved. Create a new PHP file called 
javatest.php and insert the following: 

<?php 

$system = new Ja va (' j a va . 1 ang . System ') ; 
$version = $system->getProperty ( ' java . versi on ' ) ; 
$os = $system->getProperty ( ' os . name ' ) ; 

?> 

<Hf ML> 
<HEAD> 

<fIfLE>Fun with Java and JSP</TITLE> 
</HEAD> 
<B0DY> 

<H3>We are running Java version <?php echo Iversion ?> on the 
<?php echo $os ?> platform, and it's worki ng ! </H3> 
</B0DY> 
</Hf ML> 

With luck, your browser will output something like the following when you access javatest.php: 

We are running Java version 1.4.0 on the Linux platform, and 
it's working! 

If not, it's time to troubleshoot! Consult the PHP manual or other resources listed in Appendix D for 
help and suggestions. 

The Java object 

The Java object becomes available with installation of the Java extension and is used to instantiate a 
Java class within PHP. The format is: 

new Java(class, parameters) 
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where c 1 a s s is the class being invoked and the parameters are arguments to be passed to that 
object's constructor. Parameters are optional, providing that a default constructor is available. 

r \- ?'r " * t It's important to note that no Java packages are available to PHP by default. Although, as 

••"■'-''■» in the previous example, the java.lang.* package is always available to Java and JSP 
and therefore does not need to be referenced implicitly, the complete package and class name must 
always be specified from within PHP. 

The previous example was a simple one, since we provided no arguments to the System class. System 
cannot be instantiated in Java and is referenced through static methods just as getProperty ( ) is. 
Let's take a look at a more involved example. 

With the deprecation of several Date ( ) constructors, time reporting and formatting grew in com- 
plexity in Java. Here's an example in which we print the current date and time in JSP: 

<% 

Calendar cr = new CalendarO; 

String date_time = "yyyy-MM-dd HH:mm:ss"; 

j a va . text . Si mpl eDateFormat date = 

new java.text.Simpl eDate Forma t ( da te_ti me ) ; 

String current = date . forma t ( cr . getTi me ())) ; 
%> 

<HTML> 
<HEAD> 

<TITLE>Got the time?</TITLE> 
</HEAD> 
<B0DY> 

<H3>The current date and time is: <%- current %>.</H3> 

</B0DY> 

</HTML> 

Once again, as written in PHP: 
<?php 

$cr = new Java ( ' java . 1 ang . Cal endar ' ) ; 
$date_time = "yyyy-MM-dd HH:mm:ss"; 

$date = new Java (' j a va . text . Si mpl eDateFormat ', $date_ti me ) ; 
Scurrent = date->format( $cr->getTime( ) ) ) ; 

?> 

<HTML> 
<HEAD> 
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<TITLE>Got the time?</TITLE> 
</HEAD> 
<BODY> 

<H3>The current date and time is: <?php echo $current ?>.</H3> 

</B0DY> 

</HTML> 

Errors and exceptions 

Because Java is being accessed through PHP, a Java Excepti on appears as a PHP warning in the 
browser. While a reference to a class that is misspelled or not in the cl asspath might generate an 
error such as this within Java (accompanied by a lovely stack trace): 

/var/tomcat4/work/webroot/_/test/test$jsp.java:57: Class 
org . apache . j sp . Somethi ngAmi ss not found. 

when referenced from PHP, it will simply be displayed in the browser: 
Warning: Java.lang.ClassNotFoundException 

While this warning will at least notify you that there is a problem, it doesn't provide much useful 
troubleshooting information. You can suppress the PHP warnings by using an @ prefix with your 
method calls, although we recommend against it: 

@$trouble = loutput- >pri ntl n ( ) ; 

Another method for suppressing errors is to use di spl ay_errors and set the value to 0 to cause 
errors not to display. This is accomplished within your program with the following statement: 

i ni_set( ' di spl ay_errors ' , 0); 

When an exception is thrown, it's also possible to obtain the Excepti on object from Java for more 
pertinent information. To accomplish this, the PHP Java extension provides two functions to retrieve 
the last Exception and then to clear it: j ava_l ast_excepti on_get ( ) and j ava_l ast_excep- 
ti on_cl ea r ( ) . Neither function accepts parameters. 

With version 5, PHP gained an Excepti on object of its own! You can use both the Java and PHP 
objects in conjunction to provide more helpful error information, as in Java: 

// check for a thrown exception in Java 
$exception = java_J ast_excepti on_get( ) ; 
if ($exception) ( 

$ex_msg = $excepti on->getMessage( ) ; 

// use the Java exception to throw an exception in PHP 
throw new Excepti on ( $ex_msg ) ; 
//clear this Java exception 
j a va_l ast_excepti on_cl ea r ( ) ; 

1 
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""^JJ'"r*"" , I The getMessage( ) method will provide more information than given in the warning 

but still might not be enough. Use toStri ng( ) if your exceptions are not providing 
enough useful information. 

By using both the @ prefix and these handy PHP functions, it becomes possible to exert more control 
over Java errors within PHP. 



Potential gotchas 

Expect to run into problems while trying to integrate Java and PHP. Judging from comments on PHP 
mailing lists and on various development boards, even seasoned professionals find they must exper- 
iment with both installation and implementation in order to achieve what they want. There are a few 
problems that seem to crop up most often, and you can learn from the experiences of others. 



Installation problems 

Assuming a preexisting servlet engine and working environment, most problems in getting the Java 
extension to work properly seem to begin and end in ph p . i ni . Your particular servlet engine and/ 
or platform may require more configuration. Again, check user notes online and in mailing lists and 
experiment on your own. 



It's the classpath, stupid 

A common error, especially for those not all that familiar with Java, is to neglect to include relevant 
packages, libraries, or JAR files within the cl asspath specified as an environment variable. If you 
receive a dread Cl assNotDef i ned error or something similar, check the CLASSPATH first. If not, 
then perhaps you misspelled the class name. Hey, it happens. 



Here comes that loose typing again 

PHP may not care what type your variable is, but Java certainly does. It's probably a good idea (and 
good form, when calling Java methods) to typecast your PHP variables before passing them to a Java 
object: 

lvalue = (double) lvalue; 
$sum = (int) $sum; 
Sname = (String) $name; 

Get used to typecasting variables for use with Java. As a worst-case scenario, the code may generate 
errors. At best, it may behave unpredictably. 



Speed 

Excessive referencing of Java objects can sacrifice some of the performance that PHP aficionados 
have grown so fond of. Use Java objects and methods only when necessary! 
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The sky's the limit 

Obviously, the complexity only increases when you begin to create more involved scripts. There's 
a lot of uncharted territory that you can choose to explore. Many creative uses of the Java exten- 
sion continue to be uncovered as time passes. You can even use the Java, awt . * packages to create 
graphical interfaces through PHP, though much of this is limited to CGI mode. If you can dream it 
up in Java, there's a chance you just might be able to get it to work through PHP as well. 

Here we enter the realm of experimentation. While managing to exploit the Java extension to its full 
potential may prove enjoyable and interesting for the programmer, it often doesn't make for a very 
stable or efficient application. Use it in a production environment at your own risk, and keep abreast 
of any changes posted on the PHP site. Meanwhile, load up a development machine and go to town! 



Summary 

While many similarities in syntax and object models exist between PHP and Java, differences 
abound in typing, compilation, and methodology. 

Java programmers who are working with PHP for the first time will find server-side scripting much 
more intuitive if they have experience using Java Server Pages (JSP). PHP fulfills a similar function 
and can be embedded within HTML. 

Users seeking to integrate Java and PHP have two options: the Java SAPI module and the Java exten- 
sion. Both are optional, and PHP must be rebuilt to support these options. Use of Java assumes a 
web server with installed JVM and a servlet engine such as Apache Jakarta Tomcat. Modifications 
must be made to environment variables as well as the php . i ni configuration file, and are specific to 
your particular platform and Java servlet engine. 

Objects and methods are called from PHP, instantiating the Java object. Java packages are not 
directly available to PHP and must be correctly referenced. Parameters are optional if a default con- 
structor is to be used. 

Errors generated by Java are reported as PHP warnings but can be suppressed by attaching the @ 
prefix to your PHP statements, although we strongly recommend against suppressing errors. Java 
Excepti on objects can be accessed through PHP using built-in functions, and they can be used in 
conjunction with the PHP Excepti on object. 

Java support in PHP is experimental and, as such, is subject to change in future releases. Those 
wishing to integrate Java and PHP should keep track of new releases and potential changes that 
could break their code. 
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In this chapter, we try to get the best of both client-side and server-side 
scripting by combining PHP with JavaScript. We briefly touch on the 
question of when to use which scripting language, and stylistic points 
that may be helpful when writing the code. Then we move on to pragmatic 
examples of the type you might see on a real- wo rid PHP site. 

If you've never worked with JavaScript before, you won't learn 
how just by reading this chapter. We will only touch on aspects 
of (avaScript that materially impinge upon PHP. If you're wondering what an 
onBl ur event is, we recommend Danny Goodman's superlative JavaScript 
Bible, Sixth Edition (Wiley, 2007) or Steve Suehring's JavaScript Step by Step 
(Microsoft, 2008). 



IN THIS CHAPTER 



Outputting JavaScript with PHP 
PHP as backup for JavaScript 
Static versus dynamic JavaScript 
Dynamic form generation 



Outputting JavaScript with PHP 

Because PHP is server-side and JavaScript is client-side, you may expect to 
have problems using both on the same page. In actuality, it's this difference 
that makes them such a good match. 

Although PHP offers plenty of power for creating dynamically generated 
web pages, it is strictly a server-side language. There's a common category 
of web site tasks that perhaps don't require all the processing power of a 
server and would best be done quickly — for instance, changing the look 
of a button on mouseover. JavaScript, a purely client-side language (there's a 
server-side version, but we're assuming that you've already chosen PHP on 
that end), can be easily integrated into PHP to fill in many of these gaps. 

On the other hand, client-side JavaScript (aka Javascript, JScript, 
ECMAScript) itself has many limitations. For example, because it can't 
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communicate directly with a database, JavaScript cannot update itself with fresh data, depending 
on the page. Even worse, it's impossible to depend on client-side technologies, because they may 
not be present in a visitor's browser or may be disabled. Conscientious client-side web developers 
must either decide to code probabilistically (and accept complaints from minority-browser users) 
or maintain several versions of a site at the same time. (Nonconscientious developers simply adapt 
themselves to the market-leading browser's full capabilities and damn the torpedoes . . . but that's 
another story.) PHP can help to mitigate the effects of client-side indeterminacy. 

Dueling objects 

Perhaps the biggest divergence between JavaScript and PHP is in the area of object models. The two 
are quite divergent conceptually, and they use different styles of notation. Some people consider 
this a good thing, because at least there's no chance of mixing up objects that look similar (as there 
is with, say, ASP and JavaScript). Probably just as many consider it a pain, an incompatibility, or a 
design flaw. In any case, there is no chance that you can access the same object with both PHP and 
JavaScript — so forget it. 

JavaScript is consistently object-oriented from top to bottom. Every statement requires an object and 
a method or function to be specified and may also have event handlers. JavaScript uses the so-called 
dot object notation (object . method), which is similar to that of other common programming lan- 
guages such as Java, Python, and Microsoft's VBScript. 

The downside is that JavaScript's document object model has been shakily standardized: Although, 
in theory, ECMA and the W3C shepherd the international standard, in practice the various browser 
manufacturers violate/add to this core at their whim. Proficient JavaScripters spend a good deal of 
energy keeping track of incompatibilities and workarounds for various browsers and platforms. 

PHP doesn't care what it outputs 

The main thing to keep in mind is that PHP doesn't know or care what it returns. You can (and peo- 
ple do) use PHP to write out plain text, HTML, XHTML, DHTML, JavaScript, XML, MathML, vari- 
ous graphical formats, CSS, XSL, or even (for the ironic ironists among us) ASP. No real technical 
barrier exists to having PHP output C code, although it's probably not a usage whose popularity is 
going to sweep the nation. Remember, PHP does not always output PHP — its ultimate end product 
is usually code that will be run by another application, usually a browser. 

There are a couple of ways to write out the JavaScript with PHP. The simplest is to escape from PHP 
whenever you get the urge to go client-side. This is accomplished in precisely the same way you 
would escape from HTML. 

<?php 

echo ( " Imagi ne tons of complex PHP code in this block."); 
?> 

<script 1 anguage=" JavaScri pt"> 

<!-- Hide from JavaScript disabled browsers 

document .wri te( "Stri ct separation of client-side and server-side 
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code is a good thing.") 
// end hiding --> 
</script> 
<?php 

echo("More PHP in this block."); 
?> 

Even this example doesn't show the fullest extent of PHP/JavaScript separation. A lot of JavaScript 
is actually defined within the < H E A D > element of an HTML page and simply called in the < B 0 D Y > , 
whereas PHP is generally used in the latter. 

As with HTML, there are occasions when you don't want to escape from PHP — or this style may 
just be your personal preference. In that case, you can use PHP's echo or print statements to out- 
put JavaScript. 

<?php 

echo("This is some complex PHP code."); 

echo("<script language=\"JavaScript\">\n"); 

echo("<!-- Hide from JavaScript disabled browsers\n " ) ; 

echo ( "document . wri te ( \ " St ri ct separation of client-side and 

server-side code is a good thing. \\n\" )") ; 

e c h o ( " / / end hiding - - > \ n " ) ; 

echo( "</scri pt>\n" ) ; 

echo("More PHP in this block."); 

?> 

■ j^J; ' You may run into trouble if you use script tags (for instance, <script language="PHP">) 
' to delineate PHP chunks — the PHP parser may have a hard time figuring out which 

< / s c r i p t > tag goes with what < s c r i p t > tag. Whenever possible, use the canonical < ? p h p ? > tag. 

This style is not at all incorrect, but it can be considerably harder to keep everything straight. Unless 
you're an experienced programmer, you might want to limit this style to occasions in which you 
simply call predefined JavaScript functions, such as onSubmi t events. 

r C\j s ~ F Remember to escape double quotation marks in JavaScript sections if using echo/print 
to output code. See line 3 of the preceding snippet. 

Where to use JavaScript 

Client-side JavaScript doesn't do heavy lifting, but it is faster at certain tasks and also allows for 
some effects that you can't easily duplicate with PHP. Some places you should definitely consider 
replacing or enhancing PHP with JavaScript include: 

■ Simple arithmetic in forms and calculators (such as a shopping-cart running total or a 
mortgage calculator) 

■ Simple form validation (such as making sure that e-mail addresses have @ symbols) 

■ Site navigation (such as pull- down navigation menus) 
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■ Pop-ups (alerts, search boxes) 

■ Browser events (mouseover, onClick) 



PHP as a Backup for JavaScript 

The flip side of our where to use JavaScript advice is that PHP can help caulk the cracks in JavaScript. 
Sometimes you can seamlessly implement both client-side and server-side methods of doing a task. If 
a visitor's browser is JavaScript-enabled, fine — visitors will be able to take advantage of the zippier 
method, generally without even noticing that they've had a choice. If not, at least you won't suffer the 
ignominy of totally locking them out of your site's functionality. 

A perfect example is the double-barreled pull-down menu for site navigation. JavaScript gives you 
an instant redirect, whereas PHP provides the same result after a longer wait for those without 
JavaScript-enabled browsers. This trick takes advantage of the fact that JavaScript has event hand- 
lers (for example, onChange) that work off the structure of HTML forms without requiring an 
actual button-clicking submission. Therefore, the Submit button can be reserved for PHP's use. 
Listing 39-1 shows an HTML page that uses a JavaScript onChange redirect and, if that doesn't 
work, a PHP form handler. 



LISTING 39-1 



A JavaScript and PHP navigation form (navigation.html) 

<html > 
<head> 

<title>Navigation pulldown</title> 
<script language="JavaScript"> 

<!-- 

function Browsetform, i){ 

var site = f orm . el ements [ i ] . sel ected I ndex ; 
if (site > 0)1 

top. location = form. el ements [i ]. opti ons [si te] . val ue 

1 

} 

// --> 
</ scri pt> 
</head> 

<body> 

<fonn method="post" act i on=" redi rect . php "> 
<select name="category " onChange=" Browse ( t hi s . form , 0 )" > 
<option selected val ue=0>Choose a Category</opti on> 
<option va 1 ue=" desktop. php ">Desktops</ opt ion> 
<option value="laptop.php">Laptops</option> 
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<option value="monitor.php">Monitors</option> 
<option val ue="i nput . php">Input devi ces</opti on> 
<option val ue="storage . php">Storage devi ces</opti on> 
</sel ect> 

<input type="submi t"> 
</f orm> 
</body> 
</html > 



The PHP form handler file, called redirect.php, need only have two lines: 

<?php $category = $_P0ST[ ' category '] ; 
header( " Locati on : $category"); ?> 

You could use a similar division of labor with form validation. If JavaScript is enabled, you can use 
it to make sure that zip codes have nine digits, phone numbers have ten digits, and e-mail addresses 
have both an @ and a . . If JavaScript is not enabled, you can write a little PHP script that will do the 
same things when the form is submitted and return the form with warnings if the values are bad. 

I" r* A '■ ""^~^V^j' ; ' JavaScript form validation should be relied on only for quick convenience reminders, 
never for data sanitization. 

Another kind of form is basically arithmetic — a shopping cart with running totals or a mortgage 
payment calculator. Again, you can combine both JavaScript and PHP in an arithmetic form to cover 
all the bases. 

Finally, there is one use where PHP is so much faster that you might want to replace JavaScript alto- 
gether: browser sniffing. This is done to send different versions of a file (for instance, a style sheet) 
to a visitor depending on which browser she's using. Server-side browser sniffing is vastly more 
efficient than client-side because no text is sent until the sniff has occurred. A JavaScript browser 
sniff can amount to hundreds of lines of JavaScript, which must be sent on every download whether 
the correct browser version has been detected or not. Listing 39-2 shows a very simple server-side 
browser sniff, though these can be faked by the client's browser quite easily. 



LISTING 39-2 



A server-side browser sniff (browsersniff.php) 



<?php 

if ( strpos ( $HTTP_USER_AGENT , ' MSI E ' 
headerC " Locati on : i ndex_i e . html " ; 

) elseif ( strpos ( $HTTP_USER_AGENT , 
header! "Location: i ndex_moz .html ' 

} 

?> 



> 0) ( 



1 Gecko ' 
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Static versus Dynamic JavaScript 

Although the static JavaScript-PHP form in Listing 39-1 is handy for many applications, there's one 
big problem with it: You have to maintain it by hand. Every time you decide to add a new page to your 
site, you'll have to remember to manually add it to the drop-down list. Big deal, you're thinking — but 
these are the little things that become time-sucking nightmares when you're running a huge and high- 
traffic site. 

With PHP and a database, you can update some of your JavaScript automatically when new data is 
stored in the database — or, as we might say, dynamically. You want to take this option whenever 
possible, as it will help you save time in the long run. Listing 39-3 is how you'd rewrite the form in 
Listing 39-1 for even better client/server integration. 



LISTING 39-3 



Dynamic JavaScript and PHP form (dyn_navigation.html) 



<html > 
<head> 

<title>Navigation pulldown</title> 
<script language="JavaScript"> 

<!-- 

function Browse(form, i){ 

var site = f orm . el ements [ i ] . sel ected I ndex ; 
if (site > 0){ 

top. location = form. el ements [i ]. opti ons [si te] . val ue 

) 

} 

// --> 
</ scri pt> 
</head> 



<body> 

<form method="post" acti on=" redi rect . php "> 

<select name="category " onChange=" Browse ( thi s . form , 0 ) ' 

<option selected val ue=0>Choose a Category</opti on> 

<?php 

mysql_connect( "1 ocal host" , "user", "password"); 
my s q 1 _s e 1 e c t_d b ( " s i t e_d b " ) ; 
Squery = "SELECT filename, my_text 

FROM categories 

WHERE display = 1" ; 
$result = mysql_query ( Iquery ) ; 
while ( 1 i st ( $f i 1 ename , $my_text) 



mysql_f etch_array ( $resul t ) ) ( 



print("<option value=\"$filename\"> $my_text</opti on>\n " ) ; 



?> 

</sel ect> 
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<input type="submi t"> 
</f orm> 
</body> 
</html > 



You will doubtless have realized by now that a similar technique would be valuable even if you 
were making a straight JavaScript form (such as by using the onSubmi t event handler rather than 
onChange). It would enable you to make a basic JavaScript function more flexible by allowing PHP 
to change variable values within the function before it was sent to the browser. So feel free to use 
PHP to output straight JavaScript using variables from a data source, if you like. 

Dynamically generated forms 

You can usefully extend this train of programming thought even further by setting up a series of 
dynamic drop-downs that change according to previous form inputs. PHP will fetch all the data 
from a database and load it into the HTML page, whereas JavaScript will decide which data set 
should be visible under various conditions. 

In this example, we want to help users find information on specific cars. The list of the model of 
every car made by every manufacturer is dauntingly large, too long for even a well-designed drop- 
down list. Furthermore, car names tend to be eerily similar to each other, like the first names of a 
large family of sisters in a Swedish farming village — Integra, Sentra, Jetta, Elantra, Sephia, and so 
forth. So one way to narrow things down logically is to have the user pick a manufacturer from a 
pull-down menu, which would narrow the list to only models made by that company. 

The database table we need looks like this (actually it probably doesn't if you're using a relational 
database — but here we want to focus on the JavaScript part, not the database part): 



ma ke 


model 


Audi 


A4 | 


Audi 


A6 


Audi 


A8 


Audi 


Quattro 


Chrysl er 


Cirrus 


Chrysl er 


Concorde 


Chrysl er 


PT Crui ser j 


Toyota 


Camry 


Toyota 


Corol 1 a 


Toyota 


Rav4 



Using this database table and server-side PHP scripts, you would be limited to two suboptimal 
choices. You could opt for one extremely large list (either drop-down or full page) of manufactur- 
ers and models, or you could make the visitor go through two sequential forms. But after we add 
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JavaScript to the mix, we can start a page with two drop-downs and have the contents of the second 
list change, depending on what is selected in the first. 

Our double drop-down design is based on Andrew King's very clever JavaScript code, available 
at www .webreference, com under the GNU General Public License. We used PHP simply to 
connect to the database and fetch data to populate the two-dimensional arrays from which the 
JavaScript works. All of the interesting functionality here is provided by the JavaScript portion (see 
Listing 39-4). 



LISTING 39-4 



A two-dimensional dynamic drop-down (double drop. html) 

<HTML> 
<HEAD> 

<META NAME="save" C0NTENT=" hi story "> 
<STYLE> 

.saveHi story (behavior:url (#def aul t#savehi story ) ; 1 
</STYLE> 

<SCRIPT LANGUAGE="JavaScript"> 

<!-- 

var v=false; 

//--> 
</SCRIPT> 

<SCRIPT LANGUAGE-" JavaScript! . 1"> 

<!-- 

if ( typeof ( Opt i on )+" " != "undefined") v=true; 

//--> 
</SCRIPT> 

<SCRIPT LANGUAGE="JavaScript"> 

<!-- 

// Universal Related Select Menus - cascading popdown menus 
// by Andrew King, vl.34 19990720 

// Copyright (c) 1999 internet.com LLC. All Rights Reserved. 

// Modified by Joyce Park 20000703 

// 

// This program is free software; you can redistribute it 

// and/or modify it under the terms of the GNU General Public 

// License as published by the Free Software Foundation; either 

// version 2 of the License, or (at your option) any later 

// version. 

// 

// This program is distributed in the hope that it will be 
// useful, but WITHOUT ANY WARRANTY; without even the implied 
// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
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// PURPOSE. See the GNU General Public License for more 

// detai 1 s . 

// 

// You should have received a copy of the GNU General Public 

// License along with this program; if not, write to the Free 

// Software Foundation, Inc., 59 Temple Place, Suite 330, 

// Boston, MA 02111-1307 USA 

// 

// Originally published and documented at www.webreference.com 

// see www.webreference.com/dev/menus/intro2.html for changelog 

if (v) (a=new Array(22) ; } 

function getFormNum (formName) ( 
var formNum =-1 ; 

for (i=0;i<document.forms.length;i++)( 
var tempForm = document . forms [ i ] ; 
if (formName == tempForm) ( 

formNum = i ; 

brea k ; 

) 

} 

return formNum; 



function jmp(form, elt) { 

// The first parameter is a reference to the form, 
i f ( form ! = nul 1 ) ( 

with ( f orm . el ements [el t] ) ( 
if (0 <= sel ectedlndex) 

var location = opti ons [ sel ected Index] . val ue ; 

) 

} 

} 

var catslndex = -1 ; 
var itemslndex; 

if (v) { // ns 2 fix 
functi on newCat( ) ( 
catslndex++; 

a[catslndex] = new ArrayO; 
itemslndex = 0; 



// Andrew chose to name this function "0", presumably standing 
// for "Option". It's not a zero, here or in the array below! 
functi on 0 ( txt , url ) ( 

a[catslndex][itemslndex]=new myOptions(txt,url ); 
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itemslndex++; 

} 

function myOpti ons ( text , val ue ) ( 
this. text = text; 
this. value = value; 

} 

// fill array 
<?php 

mysql_connect("localhost", "db_user"); 
my s q 1 _s e 1 e c t_d b ( " a u t o_d b " ) ; 
// Get the makes 
$i = 0; 

$make_query = "SELECT DISTINCT make FROM cars"; 

$make_result = mysql_query ( $make_query ) ; 

while ($make_row = my sql_f etch_ar ray ( $ma ke_resul t ) ) ( 

$make[$i] = $make_row[0] ; 

// Now fill the array with models for each make 
echo " newCat ( ) ; \n " ; 
$model_query = "SELECT model 
FROM cars 

WHERE make = ' $make[$i ] ' 

ORDER BY model " ; 
$model_resul t = mysql_query ( $model _query ) ; 
whi 1 e( 1 i st( $model ) = my sql_f etch_a r ray ( $model_resul t ) ) ( 
echo "0 ( \ " Imodel \ " , \ " /$model . php\ " ) \n " ; 

} 

echo " \ n " ; 
$ i ++ ; 

} 

?> 

) // close if (v) 

function rel ate ( f ormName , el ementNum , j ) 1 
if (v)l 

var formNum = getFormNum( f ormName ) ; 
if (formNum>=0) 1 

formNum++; // reference next form, assume it follows in HTML 
with ( document . forms [formNum] . el ements [el ementNum] ) { 
f or ( i =opti ons . 1 ength- 1 ; i >0 ; i - - ) options[i] = null; 
// null out in reverse order (bug workarnd) 
for(i=0;i<a[j] .length ;i++){ 

options[i] = new Opt i on ( a [ j ] [ i ] . text , a [ j ] [ i ] . va 1 ue ) ; 

} 

opti ons [0] . sel ected = true; 

1 

( 

1 else ( 
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jmp ( f ormName , el ementNum ) ; 

} 
I 

// BACK BUTTON FIX Tor ie4+- or 

// MEMORY-CACHE- STORING-ONLY -INDEX -AND- NOT-CONTENT 
// see www.webreTerence.com Tor Tull comments 
f unctl on I EsetupC ) { 

i f( ! document . al 1 ) return; 

IE5 = navi gator . appVers i on . i ndexOT( " 5 .")!=- 1 ; 
if(!IE5) ( 

Tor ( i =0 ; i <document . Torms . 1 ength ; i++) { 
document. To rms[i ] . reset( ) ; 

) 

) 

} 

wi ndow . onl oad = IEsetup; 

//--> 

</SCRIPT> 

</HEAD> 

<B0DY BGC0L0R="#ffffff"> 
<CENTER> 

<TABLE BGC0L0R="#DDCCFF" B0RDER="0" C E L LPADD I N G= " 8 " 
CELLSPACING="0"> 
<TR VALIGN="TOP"> 
<TD>Choose a make:<BR> 

<F0RM NAME="T1" METH0D=" POST" ACTION=" redi rect . php" 
onSubmi t=" return false;"> 

<SELECT NAME="ml " ID="ml" CLASS="saveHi story" 

onChange="relate(this.Torm,0,this.selectedIndex)"> 

<?php 

while (listdkey, $val ) = each($make)) ( 

echo "<0PTI0N VALUE=\ "/ ( $val } . php\ " > ( $ val } </0PTI 0N>\n " ; 

) 

?> 

</SELECT> 

<I NPUT TYPE=SUBMIT VALUE="Go" onCl i ck= "jmp ( thi s . form , 0 );" > 

</F0RM> 

</TD> 

<TD BGC0L0R="#FFFFFF" VALI GN=MI DDLEXB>- - -&gt ; </BX/TD> 
<TD>Choose a model :<BR> 

<FORM NAME="f 2" METHOD=" POST" ACTION=" redi rect . php" 
onSubmi t=" return false;"> 

<SELECT NAME="m2" ID="m2" CLASS="saveHi story" 
onChange="jmp(this.Torm,0)"> 
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// These are placeholder values for the first time the page is 

// loaded. They will not change when the form values change. 

// If you delete them, the forms will still work, but the 

// second select menu would come up empty until changed. 

// These values could be generated dynamically, but we wanted 

// to show them in place. 

<0PTI0N VALUE="/A4.php">A4< /OPTION) 

<0PTI0N VALUE="/A6.php">A6< /OPTION) 

<0PTI0N VALUE="/A8.php">A8< /OPTION) 

<0PTI0N VALUE="/Quattro">Quattro</OPTION> 

</SELECT> 

<INPUT TYPE=SUBMIT VALUE="Go" onCl i ck=" jmp ( thi s . f orm , 0 ) ; "> 

<INPUT TYPE="hidden" NAME="baseurl " VALUE="http://localhost"> 

</F0RM> 

</TD> 

</TR> 

</TABLEX/CENTER> 

</B0DY> 
</HTML> 



If you were to add to or change any of the data in the database, the JavaScript would change 
automatically. Dynamic integration of new data makes this a very powerful tool and keeps page 
maintenance to a minimum. 



Passing data back to PHP from JavaScript 

Finally, we close the data loop by passing form values back to PHP with JavaScript. Listings 39-5, 39-6, 
and 39-7 use JavaScript to force at least one check box to be checked at all times. In addition, it passes 
an array to a PHP script. We've chosen to use frames here to maximize the speed of the changes, and we 
wrote all values out by hand for clarity, rather than assembling them dynamically from a data source. 



LISTING 39-5 



Frameset (sandwich_frames.html) 

<HTML> 
<HEAD> 

<FRAMESET R0WS="50%, 50%" FRAMEBORDER="no" B0RDER=0> 

<FRAME SRC="sandwichorder.html" NAME="main" SCR0LLING="auto"> 

<FRAME SRC="results.php" NAME=" resul ts " SCR0LLING="auto"> 

</ FRAMESET) 

</HEAD> 

<B0DYX/B0DY> 

</HTML> 
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LISTING 39-6 



Form page (sandwichorder.html) 

<HTML> 
<HEAD> 

<SCRIPT LANGUAGE-" Java Script") 

<!-- 

function desel ectAl 1 Others ( boxVal s ) ( 

for (var x = 1; x < boxVal s . 1 ength ; x++) { 
boxVals[x] .checkechfalse; 

} 

} 

function confi rmOne ( boxVal s ) ( 
var count = 0; 

for (var x = 1; x < boxVal s . 1 ength ; x++) { 
if ( boxVal s [x] . checked == false) ( 
count++ ; 

) 

} 

if (count == ( boxVal s . 1 ength -- 1 ) ) ( 

boxVal s [0] . checked = true; 
( else ( 

boxVal s [0] . checked = false; 

} 



function toArray ( boxVa 1 s ) { 

for (var x = 0; x < boxVal s . 1 ength ; x++) { 
var valArray = boxVal s [x] . name+" []" ; 
boxVal s [x] . name = valArray; 

} 

} 

// --> 

</script> 

</HEAD> 

<ES0DY BGC0L0FH/FCFCF0 on Load="document . sel ector . submi t ( ) ; "> 

<TABLE CELLPADDING=20> 
<TR> 

<TD VALIGN="top"> 

<B>0rder a sandwich wi th . . . </B> 

<BRXBR> 

<F0RM NAME="sel ector" TARGET=" resul ts " METH0D="post" 
ACTION="results.php"> 

<B>Fillings (check one or more )</BXBRXBR> 

< I N PUT TYPE="checkbox" name="f i 1 1 i ng" val ue="everythi ng" 
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checked onClick="deselectA110thers(document. selector. filling); 
confirmOne(document. selector. filling); 

toArray ( document . sel ector . fi 1 1 i ng ) ; submit();"> Everything 
<BR> 

< I N PUT TYPE="checkbox" name="f i 1 1 i ng" val ue="turkey " 
onClick="confi rmOne ( document .selector. filling); 
toAr ray ( document . sel ector . fi 1 1 i ng ) ; submit();"> Turkey 
<BR> 

< I N PUT TYPE="checkbox" name="f i 1 1 i ng" val ue=" roastbeef " 

onClick="confi rmOne ( document .selector. filling); 

toAr ray ( document . sel ector . fi 1 1 i ng ) ; submit();"> Roast beef 

<BR> 

< I N PUT TYPE="checkbox" name="f i 1 1 i ng" val ue="pastrami " 
onClick="confi rmOne ( document .selector. filling); 
toArray ( document . sel ector . fi 1 1 i ng ) ; submit();"> Pastrami 
<BR> 

< I N PUT TYPE="checkbox" name="f i 1 1 i ng" val ue="eggpl ant" 

onClick="confi rmOne ( document .selector. filling); 

toAr ray ( document . sel ector . fi 1 1 i ng ) ; submit();"> Eggplant 

<BR> 

</TD> 

<TD VALIGN="top"XBRXBR> 
<B>Cheese</BXBRXBR> 

<SE LECT NAME="cheese" onChange=" submi t ( ) ; " > 
<0PTI0N VALUE="none">None</0PTI0N> 
<0PTI0N VALUE="cheddar">Cheddar</OPTION> 
<0PTI0N VALUE="swi ss">Swi ss</0PTI0N> 
<0PTI0N VALUE="camembert">Camembert</OPTION> 
<0PTI0N VALUE="bleu">Blue</0PTI0N> 
<0PTI0N VALU E="cott a ge">Cottage< /OPTION) 
</SELECT> 
<BRXBR> 
</TD> 

<TD VALIGN="top"XBRXBR> 
<B>Bread</BXBRXBR> 

<SELECT NAME="bread" onChange="submi t( ) ; "> 

<0PTI0N VALUE="white">White</OPTION> 

<0PTI0N VALUE="wheat">Wheat</OPTION> 

<0PTI0N VALUE="rye">Rye</OPTION> 

<0PTI0N VALUE="kai ser">Kai ser roll</0PTI0N> 

<0PTI0N VALUE="onion">Onion roll</0PTI0N> 

<0PTI ON VALUE="dutch">Dutch crunch</0PTI0N> 

</SELECT> 

</F0RM> 

<BRXBR> 

</TD> 

</TRX/TABLE> 

</B0DY> 

</HTML> 
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Results listing (results. php) 



<HTML> 

<HEADX/HEAD> 

<BODY BGC0L0FH/666680 TEXT=#f f f f f f > 
<TABLE CELLPADDING=30XTRXTD> 
<B>Da Resul ts</BXBRXBR> 
<?php 

$filling = $_POST[ ' f i 11 ing ' ] ; 
$cheese = $_POST[ ' cheese '] ; 
$bread = $_POST[ ' bread '] ; 

if ($f ill ing) I 

if ( i s_array ( $f i 1 1 i ng ) ) { 
reset ( $f i 1 1 i ng ) ; 

while (listdkey, lvalue) = each ( $f i 1 1 i ng ) ) ( 
echo( "$val ue<BR>\n" ) ; 

) 

( else { 
echo($filling); 

} 

} 

?> 

<BRXBRX/TD> 

<TD VALIGN=topXBRXBR> 

<B>Cheese</BXBRXBR> 

<?php echo ( Scheese ) ; ?> 

<BRXBRX/TD> 

<TD VALIGN=topXBRXBR> 

<B>Bread</BXBRXBR> 

<?php echo ( $bread ) ; ?> 

</TDX/TR> 

</TABLE> 

</B0DY> 

</HTML> 



This form admittedly doesn't actually do very much yet — but the point is that it would obviate one 
or two trips from client to server and back. It also demonstrates another of the interesting effects 
PHP developers can get by experimenting with JavaScript. 
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Summary 



JavaScript is a client-side scripting language that is highly efficient at many tasks that do not require 
server-side processing. Not everyone will want to use JavaScript, which has longstanding usability 
and security issues, but for those who do, the combination of client-side and server-side program- 
ming languages can provide an attractive variety of functionalities. 

PHP and JavaScript have different object notations. JavaScript uses the so-called dot notation, 
whereas PHP uses the arrow or C++ style notation. JavaScript is thoroughly object-oriented, whereas 
PHP treats objects as an optional feature. The good news is that you'll never confuse a JavaScript 
object for a PHP object, or vice versa. The bad news is that you cannot access the same object from 
both languages. 

It's often possible to implement a feature in both a client-side and a server-side way. Users with 
JavaScript-enabled browsers can enjoy greater speed and convenience, whereas those without can 
still get the functionality. This makes it possible to consider using JavaScript without its greatest 
drawback, which is unpredictability leading to alienation of segments of the user base. 

Perhaps the greatest service PHP can perform for JavaScript is to enable database connectivity — 
resulting in what we might call Dynamic JavaScript. JavaScript, being purely a client-side technology, 
cannot query a server-side database for variable data with which to dynamically generate content. 
Without a server-side helper like PHP, JavaScripts must be updated by hand whenever variable data 
is changed. PHP's capability to pass in up-to-date variables from a data store can make it consider- 
ably less labor-intensive to maintain JavaScript-enabled forms and functions. 
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XML is one of the hottest buzzwords in the software business today; 
but what does it mean for Joe or Jane Average PHP Developer? 
Well, it could very well be the necessary precondition for a better 
Internet — one that is faster to develop, more interactive, less junky, and 
more accessible to a larger audience. With PHP, you're already in an excel- 
lent position to smoothly integrate XML into your web development arse- 
nal as the technology matures. 



What Is XML? 



XML stands for Extensible Markup Language. XML is a form of SGML, the 
Standard Generalized Markup Language, but you don't need to know any- 
thing about SGML to use XML. It defines syntax for structured documents 
that both humans and machines can read. 



j j mi 



l Our explanation of XML will necessarily be extremely brief 
f (because this is a book about PHP rather than XML). For those 
who want to learn more, we highly recommend Elliotte Rusty Harold's XML 
1.1 Bible, Third Edition (Wiley, 2004). Although this book is neither short nor 
a specific guide to programming XML-based applications, it will give you a 
firm conceptual grasp of XML that should set you up nicely for any particular 
XML-based task. 

Perhaps the easiest way to understand XML is to think about all the things 
HTML can't do. HTML is also a markup language, but HTML documents 
are anything but structured. HTML tags (technically known as elements) 
and attributes are just simple identification markers for the browser. For 
instance, a pair of matched <H1> and </Hl> tags designates a top-level 
heading. Browsers interpret this to mean you want heading text to be 
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displayed in a really big, bold, possibly italicized font. HTML does not, however, indicate whether 
the text between those tags is the title of the page, the name of the author, an invitation to enter the 
site, a pertinent quotation, a promise of special sale prices, or what. It's just some text that happens 
to be big. 

One implication of HTML's lack of structure is that search engines have little built-in guidance about 
what's important on each page of your site or what each chunk of text means in relation to the oth- 
ers. They use various methods they can use to guess, none of which is foolproof. <META> tags are 
notoriously prone to abuse — porn sites often load popular but irrelevant search terms into their 
headers to fool unwary web surfers — and spiders can end up giving too much weight to portions of 
the page that designers might think are unimportant. If XML becomes ubiquitous, it could eliminate 
many of these problems and lead the way to much more meaningful web searching. 

Let's say you work for a content web site that has just signed a major distribution deal with a top- 
five portal. After you wake up from the champagne hangover, you're faced with the hard question 
of how you plan to deliver the content. HTML isn't going to do the job: Obviously the portal's page 
design and web-serving technology are different from your site's, and they won't be able to just plug 
your HTML into theirs. Just to make things really interesting, let's assume that you and Big Portal 
Company use different programming languages, different data stores, different HTML editors, dif- 
ferent style sheets — in short, different everything. The necessary bridge is a data-exchange format 
that is easy for you to output with your technical setup, clearly understood by both parties with 
their existing software, and equally easy for the Big Portal Company to convert to its own purposes 
and designs. XML is that data exchange format. 

You could, of course, write a script to dump data from your data store into a tab-delimited file. Then 
you could write out the details of your custom data format and send it with the tab-delimited file 
to Big Portal Company. There one of its engineers would try to figure out your schema and write 
code to transform your data into its format. However, anyone who has actually done this knows how 
much fiddly work it requires, how many tests need to be performed, and how much time even the 
tiniest error can suck up. On the other hand, you could just output your data in XML, and the Big 
Portal Company engineer could write a very short script — perhaps just three functions long — to 
transform your XML tags to its corresponding XML tags. Then Big Portal Company could treat the 
data just like its own data. XML is an attempt to move toward a common language and set of meth- 
ods for performing tasks like these, instead of having data exchange involve a series of custom jobs 
each time. 

We hope these examples begin to answer the "Why XML?" question. If you forget the hype and 
focus on what problems XML might begin to solve, you'll be in a much better position to assess 
whether it can help you today or sometime in the future. In the simplest terms, XML is a flexible 
data exchange format that is not dependent on any particular software or domain, can be parsed 
easily by both machines and humans, and allows content providers to include information about the 
structure of the data along with the data itself. 

The next question about XML is typically, "What does XML look like anyway?" Actually, XML looks 
a lot like HTML. A simple XML file, such as the one shown in Listing 40-1, is easy for HTML users 
to understand. 
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LISTING 40-1 



A simple XML file 

<?xml vers i on=" 1 . 0" ?> 
<book> 

<publisher>IDG Books</publisher> 
<title>PHP5 Bible</title> 
<chapter tit! e=" PHP and XML"> 
<section title="What is XML?"> 
<paragraph> 

If you know HTML, you're most of the way to understanding XML. 
</paragraph> 
<pa ragraph> 

They are both markup languages, but XML is more structured 
than HTML. 

< / p a r a g r a p h > 
</section> 
</chapter> 
</book> 



As you can see, XML has tags and attributes and the hierarchical structure that you're used to see- 
ing in HTML. In XML, each pair of tags (<paragraph></paragraph>)is known as an element. 
Actually, this is true in HTML, too, but most people strongly prefer the term tag (the construction 
that marks an element) over element (the conceptual thing that is being marked by a tag) — we're 
not picky. Use whatever term you want as long as you know what you mean. The biggest difference 
is that XML tags are self-defined; they carry absolutely no display directive to the web browser or 
other viewing application. 

XML makes the following minimal demands: 

■ There must be a single root element that encloses all the other elements, similar to 
<HTMLX/HTML> in HTML documents. This is also sometimes called the document element. 

■ Elements must be hierarchical. That is,<X><Y></Y></X>is allowed, but<X><Y></X> 
</Y> is not. In the first example, <X> clearly contains all of <Y>. In the second example, 
<X> and <Y> overlap. XML does not allow overlapping tags. 

■ All elements must be deliberately closed (in contrast to HTML, which allows some 
unclosed elements such as <0 PT I ON > or <LI>). This can be accomplished with a closing 
tag (< t i 1 1 e >< / 1 i 1 1 e >) as in HTML or by using an XML feature with no HTML equiva- 
lent called a self-closing element (<1 ogo h ref =" graphi c . j pg" />). A self-closing element is 
also known as an empty element. 

■ Elements can contain elements, text, and other data. If an element encloses something that 
looks like it might be XML — such as <hel 1 o> — but isn't, or if you don't want something 
parsed, it must be escaped. 
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f • ' ' ~~~ [ O* 1 ' tO h " The &, <, >, ' , and " characters are all restricted in XML. You can use them in your 



--<--w 



data by escaping them — using codes such as &amp ; and &1 1 ; — or by putting them in 
CDATA sections, which we discuss in the section "Documents and DTDs," later in this chapter. 

In addition to these mandatory requirements for what is called well-formedness, the XML standard 
also suggests that XML documents should start with an identifying XML declaration. This is a pro- 
cessing instruction giving the MIME type and version number, such as < ? xm 1 v e r s i o n = " 1 . 0 " ? > . 
This is not required, but some parsers complain if it isn't present. Also, XML is case-sensitive; some 
variants, such as XHTML, require lowercase tags and attributes. Lowercase tags are not absolutely 
required by the XML standard itself, but unless you have a good reason to do otherwise you should 
use lowercase tags and attributes. 

■ J 1 "?""'' [ '*' s *' le ^^\- declaration, and other processing instructions with the same format, that 

t .. prevents you from using PHP's short tags with XML. Because the two tag styles are iden- 

tical (<? ?>), it would be unclear whether this character sequence set off a PHP block or an XML pro- 
cessing instruction. 

XML documents are usually text. They can contain binary data, but they aren't really meant to. If 
you want to put binary data in your XML documents, you have to encode it first and decode it later. 
Note that including binary data may break some of the platform-independence of pure XML. 



Working with XML 

By now you may or may not think XML is the greatest thing since cinnamon toast, but in either case 
you're probably asking yourself, "OK, but what can I actually do with it?" This is actually not such an 
easy question to answer. In theory, you can do three main things with XML: manipulate and store 
data, pass data around between software applications or between organizations, and display XML 
pages in a browser or other application using style sheets to apply display directives. 

In practice, almost no one actually uses XML as a primary data store when SQL is so ubiquitous. It's 
possible, although still difficult, to manipulate data using XML — for instance, to edit documents 
by creating and manipulating XML nodes rather than straight text — but again many users don't see 
a tremendous amount of extra value to this practice. A great deal of progress has been made in dis- 
playing XML in the browser, generally in the form of XHTML, in the last couple of years, but there 
are still significant issues with this practice. For more information about displaying XML, see the 
sidebar "The Promises and Pitfalls of Displaying XML." 

This leaves one main job for XML right now: exchanging data between applications and organiza- 
tions. This happens to be the area in which PHP can have the most immediate impact. For instance, 
a C program might perform some operations on data from a data store and then output the results in 
XML, which PHP could transform into HTML for display in a browser or other application. 

This data flow actually makes sense if substantial amounts of computation need to happen behind 
the scenes, because you do not want to have a big program both performing complex operations and 
outputting HTML if you can possibly help it. 
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PHP can also read in data from a data store and write XML documents itself. This can be helpful 
when transferring content from one web site to another, as in syndicating news stories. You can also 
use this functionality to help nontechnical users produce well-formed XML documents with a Web 
form frontend. At the moment, writing XML might well be the most common category of XML- 
related PHP task. 

Finally, data is beginning to be manipulated and exchanged across human and nonhuman endpoints 
via the Internet itself. This technology is called Web services, and it is the subject of Chapter 41. 



Documents and DTDs 

As we explained earlier, the requirements for a well-formed XML document are fairly minimal. 
However, XML documents have another possible level of "goodness," which is called validity. A valid 
XML document is one that conforms to certain stated rules that together are known as a document 
type definition (DTD). 

To get in the mood to understand the value of DTDs, imagine that you are the head of an open 
source project that exists to make books and other documents freely available in electronic form on 
the Internet. You're very excited about XML from the moment you learn about it because it seems to 
meet your need for a data exchange format that can adapt easily to new display technologies as they 
evolve. Your group members vote to encode all the project's books and documents in XML, and soon 
the XMLized documents start to pour in. 

But when you look at the first couple of submissions, you get a rude shock. One of them is in the 
same format as Listing 40-1, earlier in this chapter, but one of them looks like what you see in 
Listing 40-2. 



LISTING 40-2 



A book in XML format 

<?xml versi on = " 1 . 0" ?> 
<book title="PHP5 Bible"> 
<publisher name="Wiley Publishing"/) 
<chapter number="40"> 
<chapter^titl e>PHP and XML</chapter_ti tl e> 
<P> 

<sentence>If you know HTML, you're most of the way to 
understanding XML. </sentence> 

<sentence>They are both markup languages, but XML is more 
structured than HTML . </sentence> 
</p> 
</chapter> 
</book> 
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The two XML files express similar, but not identical, hierarchical structures using similar but not 
identical tags. This is the potential downside of the self-defined markup tags that XML enables: 
random variation that makes it difficult to match up similar kinds of information across files. You 
quickly realize that you will need to implement some rules about what kinds of information should 
be in a book file and what the relationships between these elements will be. You've just realized you 
need a DTD. 

A DTD describes the structure of a class of XML documents. A DTD is a kind of formal constraint, 
guaranteeing that all documents of its type will conform to stated structural rules and naming 
conventions. A DTD enables you to specify exactly what elements are allowed, how elements are 
related, what type each element is, and a name for each element. DTDs also specify what attributes 
are required or optional, and their default values. You could of course just write down these rules in 
a text file: 

The top-level object of this document is a BOOK 

A BOOK has one and only one TABLE OF CONTENTS 

A BOOK has one and only one TITLE 

A BOOK is composed of multiple CHAPTERS 

CHAPTERS have one and only one CHAPTERTITLE 

All CHAPTERTITLEs are listed in the TABLE OF CONTENTS 

etc . 

You could give a copy of the list to anyone who might need it. A DTD is just a more concise, well- 
defined, generally agreed upon grammar in which to do the same thing. It's a useful discipline 
to apply to XML documents, which can be chaotic because of their entirely self-defined nature. 
Furthermore, if you can get a group of people to agree on a DTD, you are well on the way to having 
a standard format for all information of a certain type. Many professions and industries, from math- 
ematicians to sheet music publishers to human resources departments, are eager to develop such 
domain-specific information formats. 

In the previous example, which uses XML to store books electronically, your group members may 
have to argue for months before hashing out the details of a DTD that perfectly describes the rela- 
tionships between the table of contents, chapters, titles, and headings, indexes, appendices, sections, 
paragraphs, forwards, epilogues, and so on. You can, of course, iterate on DTDs as frequently as 
necessary. 

But after your DTD is finalized, you can enjoy another value-add of XML. You can now run any 
XML document through a so-called "validating parser," which will tell you whether it's meeting all 
the requirements of its DTD. So instead of a human editor having to read each electronic book sub- 
mission to see whether it has the required elements and attributes in the correct relationship, you 
can just throw them all into a parser and let it do the formal checking. This won't tell you anything 
about the quality of the content in the XML document, but it will tell you whether the form meets 
your requirements. 

In order to work with XML in PHP, you need to learn about the basic structure of DTDs and the 
XML documents they describe whether you choose to validate or not. 
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The structure of a DTD 

A document type definition is a set of rules that defines the structure of a particular group of XML 
documents. A DTD can he either a part of the XML document itself (in which case it is an internal 
DTD), or it can be located externally, in another file on the same server or at a publicly available URL 
anywhere on the Internet (in which case it is an external DTD). 

'p'rr i - " ' F Although a DTD can be internal (part of the XML document itself), making it external 
ta^in^^^K (a separate file) is usually better. DTDs are meant to define a class of documents, so 
separating them from the XML saves you from editing every XML document of that class if you need to 
change the DTD later on. Because demonstrating on an internal DTD is easier for readers to follow in a 
book format, however, we use both as examples in this chapter. 

You can start by looking at a simple XML document with an internal DTD in Listing 40-3. 



LISTING 40-3 



An XML document with internal DTD (recipe.xml) 

<?xml versi on=" 1 . 0" ?> 



<!D0CTYPE 
<! ELEMENT 
< ! ATTLI ST 
<! ELEMENT 
<! ELEMENT 
<! ELEMENT 
]> 



recipe [ 

recipe (ingredients, directions, 
recipe name CDATA #REQUIRED> 
ingredients (#PCDATA)> 
directions (#PCDATA)> 
servings (#PCDATA)> 



servings)> 



<recipe name ="Beef Burgundy"> 
<ingredients>ESeef</ingredients> 
<ingredients>Burgundy</ingredients> 
<di recti ons> 

Add beef to burgundy. Serve. 
</di recti ons> 
<servings>12</servings> 
</recipe> 



We've divided the XML document into three subsections for easier reading. The first section is the 
standard one-line XML declaration that should begin every XML document. The second section is 
the internal DTD, marked by lines beginning with the < ! sequence. The third section is the XML 
itself, strictly speaking. For the moment, we are focusing on the second section, the DTD. In our 
example, the stuff outside the square brackets is a document type declaration (not to be confused 
with document type definition) : < ! DOCTY P E recipe [. . .]>. The document type declaration gives 
information about the DTD this document is using. Because this is an internal DTD, we simply 
give the name of the root element (recipe) and then include the rest of the definition within 
square brackets. If you are using an external DTD, however, you use the document type declaration 
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to state the type and location of the DTD. Two example document type declarations referring to 
external DTDs are: 

<!D0CTYPE recipe SYSTEM " reci pe . dtd"> 

<!D0CTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Trans i ti onal // EN " 
" http : / /www .w3.org/TR/html4/loose.dtd"> 

External document type declarations give a root element name, the type (SYSTEM , meaning on the 
server, or PUBLIC, meaning a standardized DTD) and the location where it can be found. You are 
doubtless familiar with document type declarations because, without exception, you always include 
one, like the preceding example, in every single HTML or XHTML document you write — right? 

The DTD proper consists of the lines inside the square brackets. These lay out the elements, element 
types, and attributes contained in the XML document. 

■ Element: A start and end tag pair — for example, <b> something </b> — or an empty 
element (<br/>). Elements have types and sometimes content and attributes. 

■ Element Type: A constraint on the content and attributes of an element. A type can be 
used to specify what kind of data it can contain and to specify what attributes it can have. 

■ Attribute : A name and value pair associated with an element , in the form<elementattr 
ibutename="attributevalue">. 

In the example DTD in Listing 40-3, we've declared that the root element, reci pe, contains three 
child elements — ingredients, di recti ons, and servings — and has one required attribute, 
name. Each child element is of the parsed character data type, and the attribute is of the character 
data type. 

If you wanted to split up Listing 40-3 into an XML document and an external DTD, it would look 
much the same, except that, instead of providing the definition in square brackets, you would give a 
reference to the external DTD file. The result would look like Listings 40-4 and 40-5. 



LISTING 40-4 



An XML document with external DTD (recipe_ext.xml) 

<?xml vers i on=" 1 . 0 " ?> 

<!D0CTYPE recipe SYSTEM " reci pe . dtd " > 

<recipe name ="Beef Burgundy"> 
< i ng red ients>Beef</ ingredients) 
<ingredients>Burgundy</ ingredients) 
<di recti ons> 

Add beef to burgundy. Serve. 

</di recti ons> 
<servings>12</servings> 
</ reci pe> 
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LISTING 40-5 



An external DTD (recipe. dtd) 

<!ELEMENT recipe (ingredients, directions, servings)) 
< ! ATTLIST recipe name CDATA #REQUIRED> 
<! ELEMENT ingredients (#PCDATA)> 
< ! ELEMENT directions (#PCDATA)> 
< ! ELEMENT servings (#PCDATA)> 



Because the XML used in both examples conforms to the internal and external DTDs, both docu- 
ments should be declared valid by a validating parser. 

You could learn a lot more about the specifics of DTDs and XML documents, but these basics should 
enable you to understand most of PHP's XML functions. 

Validating and nonvalidating parsers 

XML parsers come in two flavors: validating and nonvalidating. Nonvalidating parsers care only that 
an XML document is well formed — that it obeys all the rules for closing tags, quotation marks, and 
so on. Validating parsers require well-formed documents as well, but they also check the XML docu- 
ment against a DTD. If the XML document doesn't conform to its DTD, the validating parser outputs 
specific error messages explaining what has gone wrong. 

PHP's SAX parser, li bxml 2, is nonvalidating (as was the expat parser used in PHP4). That doesn't 
mean that you should ignore DTDs. Going through the process of creating a DTD for each of your 
document types is a good design practice. It forces you to think out the document structure very 
carefully. And if your documents ever need to go through a validating parser, you're covered. In fact, 
many experts recommend that you put all XML documents through a validating parser even if you 
never plan to use one again. 

Most validating parsers are written in Java and are a pain to set up and use. The easiest way to vali- 
date your XML is to use an online validator. A well-known one is the STG validator at www . stg . 
brown.edu/service/xmlval id. 

Actually, using Gnome 1 i bxml to validate an XML document is possible — but it takes some work. 
Examples of validation using C are on the 1 i bxml web site (at www . xml soft . org). 



SAX versus DOM 

There are three common APIs for handling XML and XML documents: SimpleXML, the Document 
Object Model (DOM), and the Simple API for XML (SAX). All three modules are now included in all 
PHP distributions. 
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You can use the DOM, SAX, or SimpleXML API to parse and change an XML document. To create or 
extend an XML document entirely through the PHP interface (in other words, without writing any 
of it by hand), you must use the DOM. Each API has advantages and disadvantages: 

■ SAX: SAX is much more lightweight and easier to learn, but it basically treats XML as 
flowthrough string data. So if, for instance, you want to parse a recipe, you could whip up 
a SAX parser in PHP, which might enable you to add boldface to the ingredient list. Adding 
a completely new element or attribute would be very difficult, however, and even changing 
the value of one particular ingredient would be laborious. 

■ SAX is very good for repetitive tasks that can be applied to all elements of a certain type — 
for instance, replacing a particular element tag with HTML tags as a step toward transform- 
ing XML into HTML for display. The SAX parser passes through a document once from top 
to bottom — so it cannot "go back" and do things based on inputs later in the document. 

■ DOM: PHP's DOM extension reads in an XML file and creates a walkable object tree in 
memory. Starting with a document or an element of a document (called nodes in the DOM) 
you can get or set the children, parents, and text content of each part of the tree. You can 
save DOM objects to containers as well as write them out as text. DOM XML works best 

if you have a complete XML document available. If your XML is streaming in very slowly 
or you want to treat many different XML snippets as sections of the same document, you 
want to use SAX. Because the DOM extension builds a tree in memory, it can be quite the 
resource hog with large documents. 

■ SimpleXML: The SimpleXML API makes it easy to quickly open an XML file, convert some 
of the elements found there into native PHP types (variables, objects, and so on) and then 
operate on those native types as you would normally. The SimpleXML API saves you the 
hassle of making a lot of the extra calls that the SAX and DOM APIs require, uses far less 
memory than DOM XML, and often is the simplest way of accessing XML data quickly. 
There are limitations, though, including some quirky behavior related to attributes and 
deeply nested elements. 



DOM 

The Document Object Model is a complete API for creating, editing, and parsing XML documents. 
The DOM is a recommendation of the World Wide Web Consortium. You can read all about it in the 
W3's inimitable prose at www. w3.org/D0M. 

Basically the idea is that every XML document can be viewed as a hierarchy of nodes resembling 
leaves on a tree. Starting with the root element, of which all other elements can be expressed as 
children, any program should be able to build a representation of the structure of a document. 
Attributes and character data can also be attached to elements. This tree can be read into memory 
from an XML file, manipulated by PHP, and written out to another XML file or stored in a container. 
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The parser behind the scenes in PHP's DOM extension is gnome-libxml2 (aka Gnome libxmU), which 
is supposedly less memory-intensive than others. This is available at www .xmlsoft.org. 

DOM XML is the only entirely object-oriented API in PHP, so some familiarity with object-oriented 
programming helps when using it. However, there are a limited number of objects and methods, so 
you do not need any particularly deep knowledge of object-oriented programming to use DOM XML. 

Using DOM XML 

How you use the DOM will depend on your goals, but these steps are common: 

1 . Open a new DOM XML document, or read one into memory. 

2. Manipulate the document by nodes. 

3. Write out the resulting XML into a string or file. This also frees the memory used by the 
parser. 

The simple example in Listing 40-6 shows some basic DOM XML functions in use. Make sure that 
your server has its file permissions set in such a way that the web server can write a file. 



LISTING 40-6 



A simple DOM XML example (dom_example.php) 

<?php 

$doc = new DomDocument ( " 1 . 0 " ) ; 

$root = $doc->createEl ement( "HTML" ) ; 

$root = $doc->appendChi 1 d ( $ root ) ; 

$body = $doc->createEl erne nt( "BODY"); 

$body = $ root ->appendChi 1 d ( $body ) ; 

$body->setAttribute( "bgcol or" , "#87CEEB" ) ; 

$graff = $doc->createEl ement( "P" ) ; 

$graff = $body->appendChi 1 d( $graf f ) ; 

$text = $doc->createTextNode( "Thi s is some text."); 

$text = $graff->appendChild($text) ; 

$doc->save( "test_dom.xml " ) ; 

?> 



DOM functions 

Table 40-1 lists the most common DOM functions. You must call one of these functions before you 
can use any of the other DOM XML functions! 
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TABLE 40-1 




DOM XML Top-Level Function Summary 


Function 


Behavior 


domxml _open_ 
mem( stri ng ) 


Takes a string containing an XML document as an argument. This function parses 
the document and creates a Document object. 


domxml _open_ 
f i 1 e ( f i 1 ename 


Takes a string containing an XML file as an argument. This function parses the file 
) and creates a Document object. 


domxml _ Takes a string containing an XML document as an argument. Creates a tree of PHP 
xmltree(string) objects and returns a DOM object. 

Note: The object tree returned by this function is read-only. 


domxml _new_ 
doc ( vers i on ) 


Creates a new, empty XML document in memory. Returns a Document object. 


Table 40-2 lists the most important classes of the DOM API. 


TABLE 40-2 




XML DOM Class Summary 


Class 


Behavior 


DomDocument 


This class encapsulates an XML document. It contains the root element and a 
DTD if any. 


DomNode 


Encapsulates a node, aka an element. A node can be the root element or any 
element within it. Nodes can contain other nodes, character data, and attributes. 


DomAttr 


This class encapsulates a node attribute. An attribute is a user-defined quality 
of the node. 


Table 40-3 lists the most important methods of the DomDocument class. 


TABLE 40-3 




DomDocument Class Summary 


Method 


Behavior 



createElement(name) Creates a new element whose tag is the passed string. You 

must append this element to another element using DomNode- 
>appendChi 1 d ( ). 
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Method 


Behavior 


createTextNode 
( cha racter_data ) 


Creates a new text node (DomText object). You must append this 
node to another node using DomNode->appendChi 1 d ( ). 


save ( f i 1 ename ) 


Dumps XML from memory to a designated file. 


saveXMK [node] ) 


Dumps XML from memory to a string. Optional parameter is a 
DomNode object. 


Table 40-4 lists the most important methods of the DomNode class. 


TABLE 




DomNode Class Summary 


Method 


Behavior 


appendChild(newnode) 


Attaches a node to another node. 


removeChi 1 d(child) 


Removes the child node. 



Table 40-5 lists the most important methods of the DomAttr class. 



TABLE 40-5 



DomAttr Class Summary 


Method 


Behavior 


name( ) 


Returns an attribute name. 


val ue( ) 


Returns the value of an attribute. 



SAX 

The Simple API for XML is widely used to parse XML documents. It is an event-based API, which means 
that the parser calls designated functions after it recognizes a certain trigger in the event stream. 

SAX has an interesting history, especially in contrast to the DOM. The SAX API is not shepherded 
by an official standardizing body. Instead, it was hammered out by a group of programmers on the 
XML-DEV mailing list, many of whom had already implemented their own XML parsers (in Java 
first!) without a standard API. You can learn more at the web sites of SAX team members, such as 
www . saxpro j ect . org. 
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SAX works from a number of event hooks supplied by you via PHP. As the parser goes through an XML 
document, it recognizes pieces of XML such as elements, character data, and external entities. Each of 
these is an event. If you have supplied the parser with a function to call for the particular kind of event, 
it pauses to call your function after it reaches that event. The parsed data associated with an event is 
made available to the called function. After the event-handling function finishes, the SAX parser con- 
tinues through the document, calling functions on events, until it reaches the end. This process is uni- 
directional from beginning to end of the document — the parser cannot back up or loop. 

A very simple example is an event hook that directs PHP to recognize the XML element < p a r a - 
graph></paragraph> and substitute the HTML tags < p >< / p > around the character data. If you 
wrote this event hook, you could not specify a particular paragraph — instead, the function is called 
for every instance of this event. 

The parser behind the scenes in the PHP SAX extension is 1 i bxml 2, which you can read about on 
its project site at www . xml soft . org. 

Prior to version 5, PHP used James Clark's expat, a widely used XML parser toolkit. More informa- 
tion about expat can be found on Clark's web site at www .jclark.com/ xml. If you compile with 
1 i bxml 2, you should be able to use all your PHP4 SAX code in PHP6 without problems. 

r- 1 ' '"--[ Unfortunately, the term parser can refer either to a software library such as 1 i bxml 2, or 

s -'- r - w t 0 a block of XML-handling functions in PHP. Verbs such as create and call indicate the 

latter, more specific meaning. Any PHP XML function that uses the term parser also refers to the latter 

meaning. 

Using SAX 

How you use the SAX will depend on your goals, but these steps are common: 

1 . Determine what kinds of events you want to handle. 

2. Write handler functions for each event. You almost certainly want to write a character data 
handler, plus start element and end element handlers. 

3. Create a parser by using xml_pa rser_create ( ) and then call it by using xml_pa rse ( ) . 

4. Free the memory used up by the parser by using xml_pa rser_f ree ( ) . 

The simple example in Listing 40-7 shows all the basic XML functions in use (see recipe. xml from 
earlier in the chapter for the XML file used in this example). 



LISTING 40-7 



A simple XML parser (simpleparser.php) 

<?php 

$f i 1 e = " reci pe . xml " ; 

// Call this at the beginning of every element 
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function sta rt El ement ( Spa nser , $name, $attrs) ( 
pni nt "<B>$name =></B> " ; 

} 

// Call this at the end of eveny element 
function endEl ement( Sparser , $name) ( 
print " \ n " ; 

) 

// Call this whenever there is character data 
function characterData ( Sparser , lvalue) ( 
print " $ v a 1 ue<BR> " ; 

1 



// Define the parser 

$simpl eparser = xml_parser_create( ) ; 

xml _set_el ement_handl er($simpleparser, " sta rt El ement" , 
"endEl ement" ) ; 

xml _set_cha racter_data_handl er($simpleparser, "characterData"); 



// Open the XML file for reading 
if (!($fp = fopen($file, "r"))) ( 
die("could not open XML input"); 

} 



// Parse it 

while ($data = fread($fp, f i 1 esize($f i 1 e) ) ) { 

if ( ! xml _pa rse ( $s i mpl epa rser , $data, feof($fp))) { 

di e ( xml_er ror_stri ng ( xml_get„error_code ( $simpleparser))); 

! 

} 



// Free memory 

xml _pa rser_f ree ( $simpleparser) ; 
?> 



SAX options 

The XML parser in the SAX API has two configurable options: one for case folding and the other for 
target encoding. 

Case folding is the residue of a series of past decisions and may not be relevant now that XML has 
been definitely declared case-sensitive. Early versions of SGML and HTML were not case-sensitive 
and, therefore, employed case folding (making all characters uppercase or lowercase during pars- 
ing) as a means of getting a uniform result to compare. This is how your browser knew to match up 
a < P > tag with a < / p > tag. Case folding fell out of favor due to problems with internationalization, 
so after much debate XML was declared case-sensitive. When case folding is enabled, node names 
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passed to event handlers are turned into all uppercase characters. A node named mynode would 
be received as MYNODE. When case folding is disabled, a <paragraph> tag will not match a </ 
PARAGRAPH) closing tag. 

j j , ~r*""' I Case folding is enabled by default, which violates the XML 1.0 specification. Unless you 
— disable it by using xml _pa rser_set_opti on () as explained in a moment, your event 

handlers receive tags in uppercase letters. 

Event handlers receive text data from the XML parser in one of three encodings: 1SO-8859-1, 
US-ASCII, or UTF-8. The default is ISO-8859-1. The encoding of text passed to event handlers is 
known as the target encoding. This is, by default, the same encoding as in the source document, 
which is known as the source encoding. You can change the target encoding if you need to process the 
text in an encoding other than the encoding it was stored in. 



PHP and Internationalization 

Computer programs store letters as integers, which they convert back to letters according to encodings. Early 
programs used English, which conveniently needs only 1 byte (actually only 7 bits) to represent all the 
common letters and symbols. This encoding standard was promulgated in 1968 as ASCII (American Standard 
Code for Information Interchange). 

However, programmers soon found that English has an unusually small number of characters, and thus the only 
languages that can be expressed with any completeness in ASCII are Hawaiian, Kiswahili, Latin, and American 
English. Ever since then, programmers concerned with internationalization have tried to promote encoding 
standards that promise to assign a unique integer to every one of the letters of every one of the world's alpha- 
betical languages. The result of this effort is referred to as Unicode. 

The three encodings supported by PHP's XML extension are ISO-8859-1, US-ASCII, and UTF-8. US-ASCII is 
the simplest of these, a slight renaming of the original 7-bit ASCII set. ISO-8859-1 is also known as the Latinl, 
Western, or Western European encoding. It can represent almost all western European languages adequately. 
UTF-8 allows the use of up to 4 bytes to represent as many of the world's languages as possible. If your XML 
document is written in Han-gul or Zulu, you have no choice but to use UTF-8. 



Encoding options are retrieved and set with the functions xml_parser_get_option( ) and xm 1 _ 
pa rser_set_opt i on ( ) . Case folding is controlled by using the constant XML_0PTI0N_CASE_ 
F 0 L D I N G , and target encoding by using the constant X M L_0 P T 1 0 N_T A RG ET_ ENCODING. 

In the following example, we create an XML parser that reads in data as ASCII, turns off case fold- 
ing, and spits out the output as UTF-8. 

$new_parser = xml_parser_create( ' US-ASCI I ' ) ; 

$case_fol ding = xml_parser_get_opti on( XML_OPTION_CASE_FOLDING) ; 
echo $case_f ol di ng ; 



662 



Integrating PHP and XML 



40 



$change_f ol di ng = xml_pa rser_set_opti on ( $new_pa rser , XML_OPTION_CASE. 
FOLDING, 0) ; 

$target_encodi ng = xml_pa rser_get_opti on ( XML_TARGET_ENCODI NG ) ; 
echo $ta rget_encodi ng ; 

$change_encodi ng = xml_parser_set_opti on ( $new_parser , XML_0PTI0N_ 
TARGET_ENCODING, 'UTF-8'); 

SAX functions 

Table 40-6 lists the most important SAX functions, with descriptions of what they do. 



TABLE 40-6 



XML SAX Function Summary 


Function 


Behavior 


xml _pa rser_ 
rrpatpf Tpnrodi nnl ) 


This function creates a new XML parser instance. You may have several distinct 
parsers at any time. The return value is an XML parser or false on failure. 
Takes one optional argument, a character-encoding identifier (such as UTF-8). If 
no encoding is supplied, ISO-8859-1 is assumed. 


xml_parser„ 
free(parser) 


Frees the memory associated with a parser created by xml_parser_ 
create! ). 


xml _pa rse ( parser, 
data [ , fina 1 ] ) 


This function starts the XML parser. Its arguments are a parser created by 
using xml_parser_create( ), a string containing XML, and an optional 
finality flag. The finality flag indicates that this is the last piece of data 
handled by this parser. 


xml_get_error_ 
code ( parser) 


If the parser has encountered a problem, its parse fails. Call this function to 
find out the error code. 


xml_error_ 

s t r i ng ( er rorcode ) 


Given an error code returned by xml_get_error_code( ), it returns a 
string containing a description of the error suitable for logging. 


xml _set_el ement_ 
handler! parser, 
sta rt_el ement_ 
handler, end_ 
el ement_handl er ) 


This function actually sets two handlers, which are simply functions. The first 
is a start-of-element handler, which has access to the name of the element 
and an associative array of its elements. The second is an end-of-element 
handler, at which time the element is fully parsed. 


xml_set_character_ 
data_handl er(parser, 
cd_handl er ) 


Sets the handler function to call whenever character data is encountered. The 
handler function takes a string containing the character data as an argument. 


xml_set_defaul t_ 
handler! parser, 
handl er ) 


Sets the default handler. If no handler is specified for an event, the default 
handler is called if it is specified. 

Takes as arguments the parser and a string containing unhandled data, such 
as a notation declaration or an external entity reference. 
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SimpleXML API 

The SimpleXML API was new in PHP5. Characterized as an object-mapping API, SimpleXML dis- 
penses with web standards and absolute flexibility in favor of simplicity and modest memory usage. 
If you just need to read some data from an XML document and write some other data back in, the 
SimpleXML likely will require the fewest lines of code of all possible approaches to the problem. 

Here's the idea behind SimpleXML: As in the DOM approach, SimpleXML parses an XML docu- 
ment and holds the whole thing in memory. However, rather than hold the document as a DOM 
object (which you must further manipulate before you can use its contents), its elements are stored 
as native PHP variables and so are immediately usable. Because many DOM tasks do not actually 
require you to traverse all the children and parents of a document, but rather perform repetitive 
tasks on well-defined nodes, SimpleXML ultimately constitutes a PHP-specific compromise between 
the SAX and DOM approaches. 

Using SimpleXML 

When using SimpleXML, you read a passage of XML text — either a string or a file — into a variable 
with the function s i mpl exml _1 oad_stri ng ( ) or s i mpl exml _1 oad_f i 1 e ( ) . You then have a 
local object you can refer to directly. Listing 40-8 shows how the SimpleXML API can be used to get 
variable values out of an XML file with just a few lines of code. 

Listing 40-8 demonstrates a typical use of SimpleXML. 



LISTING 40-8 



SimpleXML sample (simplexml.php) 

<?php 

$recipe = s i mpl exml _J oad_fi 1 e (" reci pe . xml ") ; 

$ingredients = $recipe-> ingredients; 
$directions = $reci pe->di recti ons ; 
$servings = $recipe->servings; 

foreach ( $ i ngredi ents as $ingredient) 
{ 

print " <P> I ngredi ent : $i ngredi ent" ; 

1 

print " < P > D i recti ons : $di recti ons " ; 
print "<P>Serves $servings"; 

?> 
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SimpleXML functions 

Table 40-7 lists the most important SimpleXML functions, with descriptions of what they do. 



TABLE 


SimpleXML Function Summary 


simpl exml_l oad_ 
file(file) 


Import and parse a file. 


simpl exml_l oad_ 
string(string) 


Import and parse a string. 


si mpl exml_i mport_ 
dom( DomDocument ) 


This function allows you to convert a DomDocument object into a 
SimpleXML object, and then treat it just like an imported XML file or string. 



A Sample XML Application 

This series of scripts will write out XML to a file by using data from an HTML form and then will 
allow you to edit the values in that file. 

Listing 40-9 is an HTML form that can be used by nontechnical users to define forms. (They don't 
care that this data will be formatted and stored in XML.) Listing 40-10 is a script to write out the 
XML file. 



LISTING 40-9 



A form to collect values for an XML file (pollform.php) 

<HTML> 
<HEAD> 

<TITLE>Make-a-polK/TITLE> 
</HEAD> 

<B0DY> 

<CENTERXH3>Make-a-pol K/H3X/ CENTER) 

<P>Use this form to define a p o 1 1 : < / P > 
<F0RM METHOD="post" ACTION="wri tepol 1 . php"> 

<P>Give this poll a <B>short</B> name, like <F0NT C0L0R="red">Col or PolK/ 
FONT) . <BR> 

<INPUT TYPE=TEXT NAME=" Pol 1 Name" SI ZE=30> 
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</P> 

<P>This poll should <B>begin</B> on this date (MM/DD/YYYY ) : 

<INPUT TYPE=TEXT Name="Poll_Startdate" SIZE=10> 

</P> 

<P>This poll should <B>end</B> on this date (MM/DD/YYYY): 

<INPUT TYPE=TEXT NAM E=" Pol l_Enddate" SIZE=10> 

</P> 

<P>This is the poll question (<F0NT C0L0R=" bl ue">e . g . Why did the chicken 
cross the road?</F0NT>) : 

<INPUT TYPE=TEXT NAME=" Pol l_Questi on " , size=100> 
</P> 

<P>These are the potential answer choices you want to offer (<F0NT 
COLOR="darkgreen">e.g. Yes, No, Say what?</ F0NT> ) . Fill in only as many as 
you need. Keep in mind that brevity is the soul of good pol 1 -ma ki ng . <BR> 



<INPUT TYPE= 


TEXT 


NAME= 


' Raw_ 


.Pol 1 


_0pt i on [ ] " 


SI ZE= 


25><BR> 


<INPUT TYPE= 


TEXT 


NAME= 


' Raw_ 


.Pol 1 


_0pt i on [ ] " 


SI ZE= 


25><BR> 


<INPUT TYPE= 


TEXT 


NAME= 


' Raw_ 


.Pol 1 


_0pt i on [ ] " 


SI ZE= 


25><BR> 


<INPUT TYPE= 


TEXT 


NAME= 


' Raw_ 


.Pol 1 


_0pt i on [ ] " 


SI ZE= 


25><BR> 


<INPUT TYPE= 


TEXT 


NAME= 


' Raw_ 


.Pol 1 


_0pt i on [ ] " 


SI ZE= 


25><BR> 


<INPUT TYPE= 


TEXT 


NAME= 


' Raw_ 


.Pol 1 


_0pt i on [ ] " 


SI ZE= 


25><BR> 


</P> 
















<INPUT TYPE= 


"submit" NAME=' 


Submit" VALUE= 


'Add a 


pol 1 "> 


</F0RM> 
















</B0DY> 
















</HTML> 

















LISTING 40-10 



A script to write out an XML file (writepoll.php) 

<html > 
<head> 

<title>Write an XML file</title> 
</head> 

<body> 
<?php 

$pol I f i 1 e = "pol 1 . xml " ; 
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// Reading in the xml file as a string 

$fd = f open ( $pol 1 f i 1 e , "r") or die("Can't open file."); 

$fstr = fread($fd, f i 1 es i ze ( $pol 1 f i 1 e ) ) or die("Can't read file, check 

permi ssi ons . " ) ; 

fclose($fd) ; 

// Format response sets. 

$PollName = str_repl ace( "\ "' , "", $_POST["Pol 1 Name"] ) ; 
$PollName = str_repl ace( " ", "_" , $„POST["Pol 1 Name"] ) ; 

$RespSet = " " ; 

for ($r=0; $r<=5; $r++) { 

IcurrentRawPollOption = $_POST[ " Raw_Poll_Opti on " ] [$r] ; 
if (!empty($^POST["Raw_Poll_Option"][$r])) { 

$ Pol l_Option[$r] = " $„POST[ Pol 1 Name] -". str_repl ace ( , "", 
ScurrentRawPollOption); 

$ Pol l_Option[$r] = "$_POST[Pol 1 Name]-" . str_repl ace( " ", "_" , 
IcurrentRawPollOption); 

IcurrentPol 1 Opti on = $ Pol l_Opti on[$r] ; 

$RespSet .= "\t<response i d=\ " IcurrentPol 1 Opti on\ " >$cur rent RawPol 1 Opti on</ 
response>\n " ; 

} 



I 

//Add new pol 1 data 

$separator = "</Poll>"; 

Sdivide = expl ode( Sseparator , $fstr); 

$gl ue = 

"\t<Pol 1 name=\"$_POST[Pol 1 Name]\"/> 
</ Pol 1 Li st> 

<Pol 1 id=\"$^POST[PollName]\"> 
\t<StartDate>$^POST[Pol l_Startdate]</StartDate> 
U<EndDate>$_POST[Pol l_Enddate]</EndDate> 
\t<name>$_POST[Pol 1 Name]</name> 
\t<text>$_POST[Pol l_Question]</text> 
\t<di splay type=\ " Ba r_Graph\ " /> 

\t<responseSet resource=\"$PollName-responseSet\"/> 
</ Pol 1 > 

<responseSet id=\"$PollName-responseSet\"> 
$RespSet</responseSet> 
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Snewxml = impl ode( $gl ue , $divide); 
//Write to file 

$fd = f open ( $pol 1 f i 1 e , "w") or die("Can't open file for writing; check file 
permi ss i ons " ) ; 

$writestr = fwrite($fd, Snewxml); 
//Message 

echo "Wrote Swritestr chars to Spollfile."; 

?> 

</body> 
</html > 



Listing 40-11 shows the XML file where our polls are stored, with one poll already defined for you. 
If you add a new poll, it will be appended near the top of this file, and its name will be added to the 
PollList. 



LISTING 40-11 



An XML file (poll.xml) 

<?xml vers i on = " 1 . 0 " ?> 
<Pol 1 Defs> 

<Poll id="Best_Text_Editor"> 

<StartDate>01/01/2003</StartDate> 
<EndDate>01/31/2004</EndDate> 

<questi on>Whi ch is the best programmer's edi tor?</questi on> 

<di spl ay type="Bar)Graph"/> 

<responseSet> 

<response i d="Best_Text_Edi tor-emacs">emacs</response> 
<response i d="Best_Text_Edi tor-vim ">vim</ response) 
<response i d="Best_Text_Edi tor-notepad ">notepad</response> 
<response i d = "Best_Text_Edi tor-kate">kate</response> 
<response resource=" Best_Text_Edi tor- BBEdit">BBEdit</ response) 
</ responseSet) 
</ Pol 1 > 

< Pol 1 i d=" Best_Poi nter_Devi ce"> 
<StartDate>02/01/2004</StartDate> 
<EndDate>02/29/2004</EndDate> 

<questi on>Whi ch is the best pointer devi ce?</questi on> 

<di spl ay type="Bar_Graph"/> 

<responseSet> 

< response i d=" Best_Poi nter -mouse ">Mouse</ response) 

< response id=" Best_Poi nter-trackball">Trackball</ response) 

< response i d=" Best_Poi nter-touchpad">Touchpad</response> 
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<response id="Best_Pointer-trackpoint">TrackPoint</response> 
<response id="Best_Pointer-pen">Pen</response> 
< response i d= " Bes t_Po i nter- sty 1 us ">Stylus</ response) 
</ responseSet> 
</ Pol 1 > 

</Pol 1 Defs> 



Listing 40-12 shows a script that will allow you to edit the XML file in Listing 40-10 using DOM 
XML. 



LISTING 40-12 



XML editor (dom polledit.php) 

<html > 
<head> 

<ti tl e> Pol l XML editor</title> 
</head> 

<body> 
<?php 

$doc = new DomDocument ( ) ; 
$pol I f i l e = "poll. xml " ; 



// Handle form submission 
if ($_P0ST[ 'stage'] == 1) ( 

// Reading in the XML file as a DOM object 
if (!$doc->load($pollfile)) ( 
echo "Cannot read XML file."; 
exit; 

} 

// Once a poll is created, the user will only be able to 

// change the StartDate, EndDate, Question, and response values. 

// Format the data 
$pollname = $_P0ST[ ' pol l_name ' ] ; 
$startdate = $_P0ST[ ' Pol 1 _Sta rtdate ' ] ; 
$enddate = $_P0ST[ 1 Pol l^Enddate ' 1 ; 
$question = $_P0ST[ ' Pol l_Questi on ' ] ; 

// Replace the values as text nodes 

$poll_list = $doc->getEl ementsByTagname( "Pol 1 " ) ; 

foreach ($poll_list as Spoil _ob j ) { 
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// Figure out which poll we're editing, then work on its children 
$pol 1 name_val ue = $pol l_ob j ->getAttri bute ( " i d " ) ; 
if ( $pol 1 name_val ue == $pollname) ( 
Ichildren = $pol l_obj - > c h i 1 dNodes ; 
foreach (Schildren as $child_obj) { 
$node_name = $chi 1 d_obj ->nodeName ; 
lvalue = $chi 1 d_obj ->nodeVal ue ; 
if ($node_name == "StartDate") ( 
if (lvalue == Sstartdate) ( 

// Do nothing 
) else ( 

$sd_textnode = $ c h i 1 d_obj ->f i rstChi 1 d ; 

$new_sta rtdate = $doc- >crea teTextNode ( $sta rtdate ) ; 

$ c h i 1 d_ob j ->replaceChild( $new_st a rtdate , $sd_textnode ) ; 

) 

1 

if ($node_name == "EndDate") ( 
if (lvalue == Senddate) ( 

// Do nothing 
) else ( 

$ed_textnode = $ c h i 1 d_obj ->f i rstChi 1 d ; 

$new_enddate = $doc->createTextNode ( Senddate ) ; 

$ c h i 1 d_ob j ->replaceChild( $new_enddate , $ed_textnode ) ; 

) 

I 

if ($node_name == "question") { 
if (lvalue == Senddate) ( 

// Do nothing 
) else ( 

$q_textnode = $ c h i 1 d„obj ->fi rstChi 1 d ; 

$new_questi on = $doc->createTextNode( Squesti on ) ; 

$ c h i 1 d_ob j ->replaceChild( $new_questi on , $q_textnode ) ; 

) 

1 

if ( $node_name == "responseSet" ) ( 

$ol d„responses = $ c hi 1 d_obj - > c h i 1 dNodes ; 
$i=0; 

foreach ( $ol d_responses as $del ete_responses ) { 
if ( $del ete_responses->nodeName == 'response') { 
$r_textnode = $del ete_responses->fi rstChi 1 d ; 
$new_response = $doc->createTextNode( $_P0ST[ ' response '] [$i ]) ; 
$del ete_responses ->repl aceChi 1 d ( $new_response , $ r_textnode ) ; 
$ i ++ ; 

1 

) 

1 

) 

) 
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) 

// Write out the file 
$doc->save($pollfile) ; 



// This stuff happens every time, whether a submission 
// has occurred or not. 

// Reading in the XML file as a DOM object 
// Must read fresh every time 
if ( !$doc->load($pollfile)) ( 

echo "Cannot read XML file."; 

exit; 

} 

// Get a list of the polls in this XML document 
// and then pull out the start date, end date, 
// poll question, and possible responses. 
$poll_list = $doc->getEl ementsByTagname ( ' Pol 1 ' ) ; 
foreach ($poll_list as $poll_obj) { 

$id = $poll_obj->getAttri bute( "id" ) ; 

$children = $pol l_obj ->chi 1 dNodes ; 

foreach ($children as $key=>$chi 1 d_obj ) ( 
$node_name = $ c h i 1 d_obj ->nodeName ; 

if ($node_name != "#text" && $node_name != ' responseSet ' ) ( 

$content_str = $chi 1 d_obj ->nodeVal ue ; 

$pol 1 _a r ray [ " $node_name" ] = $content_str ; 
) elseif ( $node__name == 'responseSet') ( 

// Get the responses 

$ responsel i st = $ c h i 1 d_obj - > c h i 1 dNodes ; 
foreach ($ responsel i st as $responses) ( 

$response_name = $responses->nodeName ; 

if ( $response_name != "#text") ( 

$response_array[] = $ responses ->nodeVa 1 ue ; 

) 

1 

) 

} 

// Arrange all the data nicely 

$pol 1 _sta rtdate = $pol l_array [ ' StartDate ' ] ; 

$pol 1 „enddate = $pol l_array[ ' EndDate ' ] ; 

$poll_name = $pol 1 _a r ray [' name '] ; 

$pol l_questi on = $pol l_array [ ' questi on ' ] ; 

$pol l_questi on = stri psl ashes ( $pol l_questi on ) ; 
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foreach ($response_array as $key=>$val ) { 

$resp_str .= "Option: < INPUT TYPE=\ "text\ " SI ZE=25 NAME=\"response[$key]\" 
VALUE=\"$val \"><BR>\n" ; 
} 

// Display form with old values 
$php_self = $_SERVER[ ' PHP_SELF' ] ; 
$form = <<< EOFORM 

<F0RM METHOD="post" ACTI0N=" $php_sel f "> 

Start Date: <INPUT TYPE="text" SIZE=10 NAME="Pol l_Startdate" VALUE="$pol 1_ 
startdate"XBR> 

End date: <INPUT TYPE="text" SIZE=10 NAME=" Pol l_Enddate" VALUE="$pol 1_ 
enddate"XBR> 

Poll question: <INPUT TYPE="text" S I ZE=100 NAME=" Pol 1 _Ques ti on " VALUE="$pol 1_ 
quest i on "><BR> 
$ resp_str 

<INPUT TYPE="hidden" NAME="pol l_name" VALU E= " $ i d " > 
<INPUT TYPE="hidden" NAME="stage" VALUE=1XBR> 
< INPUT TYPE="submit" VALUE="Presto-chango"> 
</F0RM> 



EOFORM; 

echo $form; 
unset ( $ resp_str ) ; 
unset ( $ response_a rray ) ; 

} 

?> 

</body> 
</html > 



Gotchas and Troubleshooting 

The DOM and SAX parsers will only parse a well-formed XML document. If the parser rejects your 
XML, make sure that it is well formed. If it looks good to your eye, run it through a different validat- 
ing parser or an online XML checker, such as the one at www . xml . com/xml /pub/tool s / ruwf / 
check . html . 

If you cannot read and write XML documents to disk, check that the web server process has permis- 
sion to do so. 

If the DOM API returns a fatal junction not found error, the DOM XML module may not be installed. 
Use the phpi nf o( ) function to check for a domxml entry. If it isn't there, you will have to recompile 
PHP with the DOM XML module (on Unix) or uncomment the php_domxml . dl 1 line in php . i ni 
(on Windows). 
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Summary 

XML is an application-independent data exchange format that promises to make web development 
faster and easier in the future. XML and HTML are both descended from SGML, accounting for their 
close resemblance at first glance. Both have tags (more correctly called elements) and attributes, 
although XMLs are self-defined and structured whereas HTMLs are defined by the HTML standard 
and contain no information about document structure. 

XML has only a few minimal requirements for well-formedness. These include closed elements, no 
overlapping elements, escaped special characters, and the presence of a single root element for each 
document. XML can also be valid, however, in the sense of conforming to a formal declaration of 
its structure in a document type definition or DTD. DTDs can be internal or external to the XML 
document and even located on another server. They contain declarations of the types, attributes, and 
names of the various elements within the XML file. 

For the present, few prefabricated tools are available to help you write, edit, and display XML. You 
can use one of the three PHP XML APIs — SAX, DOM, and SimpleXML — to write your own tools. 
The APIs have different tradeoffs and uses. SAX is an event-based parser, whereas DOM XML creates 
an object tree in memory. SimpleXML is easy to use and requires little code, but it is relatively lim- 
ited in its capability. It's mainly useful for quick reads of simple XML files. 

At the moment, PHP with the SAX extension can be used to write out well-formed XML from values 
entered into a Web form and to edit XML documents. DOM XML can be used to create complete 
XML documents programmatically. The SAX parser is also commonly employed to transform XML 
into HTML for less problematic display in current web browsers. Another possible task for PHP's 
XML extensions is to pull data from a data store and write it out as XML for exchange with another 
organization. 
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Web services are an emerging field of programming that seeks to 
apply the benefits of the web to bigger problems than merely 
displaying data in a browser. PHP, which has already proven 
itself as a core glue component of the web, has the opportunity to grab even 
more market share in the Web services arena. As is true of other hot tech- 
nologies such as XML, however, a world of hype surrounds Web services. 
Here we try to cut through the buzzwords and analyst predictions to look 
at what Web services mean to the average PHP developer. 



The End of Programming as 

We Know It 

The title of this section is a bit of a joke — one of us works in the Web ser- 
vices field and often hears presentations that assert things such as: "In 10 
years, we will have no more need for programmers, because Web services 
will eliminate duplication of effort." Many people have thought that program- 
ming was about to die out, and all of them have been wrong so far — but 
hope springs eternal in the pundit's breast. Notching down the hyperbole to 
manageable levels, we can say that Web services could make some common 
but hard tasks in commercial computer programming a lot easier. 

The ugly truth about data movement 

Joking aside, Web services do solve some problems — at the moment largely 
in the realm of moving data around. Later in this chapter, for example, we 
offer code for a client to the Amazon REST service. This code enables you to 
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The promise of Web services 

REST, XML-RPC, SOAP 

Issues with Web services 

Project: a REST client 

Project: a SOAP client and 
server 
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grab the latest data about a given product or group of products — photos, current prices, availability, 
and so on — up to once per second via an automatic process. 

If you're a first-time author who has a small informational site with one link to Amazon, this isn't 
really going to help you much. But there are Amazon Associates who link to thousands or even mil- 
lions of products. They did so until recently by horrible hacks involving downloading all those web 
pages and using some kind of string or XPATH parsing to pick out the three or four pieces of data 
they wanted from each page. Furthermore, each client organization did all this work for itself — 
because, among other things, this is a totally unauthorized use of Amazon's copyrighted material, so 
they can hardly expect Amazon to help them. Harvesting data from full HTML pages is tremendously 
wasteful and expensive for both Amazon and the Associate — so much so that it's a good way to get 
banned from Amazon altogether. Slamming the door on requests from a particular IP block is almost 
the only way to control access to a public web server. 

Even if an organization wants to give you large amounts of information in a data feed, the mechanics 
right now are not very elegant. We are aware of many large and well-respected data-related businesses 
that move data around in text files (or spreadsheets) that are downloaded via some mechanism such 
as FTP (or e-mail) and parsed on both ends by custom Perl code (or by hand). Often, there is no way 
to send only data that has changed — the feeds are dumped out and processed in a dumb way every 
so often, rather than updating only if and when changes occur. Obviously, these are all batch pro- 
cesses, which have no possibility of working in real time. XML-based Web services promise to offer 
a common language, a common transport mechanism, a common authentication and authorization 
method, and potentially common code for organizations to access each other's data. 

If Web services were just about moving data around, the idea would be extremely useful but not at 
all sexy. What excites everyone about Web services is the promise that they can help solve the hard- 
est problems of distributed computing once and for all. 

Brutal simplicity 

Think back, if you can, to the bad old days before the web. If you can go back far enough, think 
back to the days when the Internet itself was a rarity and networking something limited to high-end 
universities (it may help to remember that for a long time one of Apple's selling points in college 
computer labs was AppleTalk). 

Back in those dark days, my children, things such as operating systems and programming lan- 
guages were major barriers to integration — they were little islands in the sea of incompatibility. If 
you were going to write an application, you were specifically writing it for a particular platform and 
language — sometimes even for a particular version of a compiler. It was very, very hard to make 
one program talk to another program. If you wrote a COBOL program on a VAX, that was where it 
was going to stay. With a great deal of effort you could get one program to send something simple, 
such as ASCII data, to another — but any little thing could mess up your interapp communication. 
If you changed anything on one side, it might mean that you had to change a bunch of stuff on the 
other side, too. These programs were said to be tightly coupled. 
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This meant a lot of duplication of effort. Porting was technically difficult, and the market was frag- 
mented. So a team that wrote an application — say, an accounting program — for Minicomputer 
X was not necessarily going to have the resources to do the same for Microcomputer Y. Lots of 
teams wrote lots of accounting programs, and all the formats were proprietary. None of them could 
exchange data with each other, much less share tasks easily. 

Slowly, mankind groped toward a way to make programs talk to each other. The blanket term for 
this activity was distributed computing. It took until the mid-1990s for these methods to reach the 
common programmer, in the form of standards such as DCOM, CORBA, and Java RMI. These stan- 
dards enabled all programs that shared a common architecture to call each other's methods and 
send data back and forth. When you are able to embed a spreadsheet inside a word processor docu- 
ment, it's via the magic of DCOM. 

These common object models, however, had three major problems. They were still more or less tied 
to particular platforms or programming languages; they were considered difficult to learn, and they 
reached general usability at the same moment that the web arrived to tantalize us with the possibil- 
ity of Internet-scale loosely coupled, distributed computing based on open standards. 

The web is the biggest, most open, most loosely coupled — and most successful — distributed archi- 
tecture of all time. With few exceptions, no web server cares which web browser is asking it for a 
page, or what operating system that browser is running on, or what chip is running the hardware 
on which that operating system lives. The application asking for the page doesn't even need to be a 
browser — it may be a spider from a search engine, it may be an f open ( ) call from a PHP command- 
line script, or it may be a cellular phone. The HTML it sends may not render nicely on every device, 
but that has nothing to do with whether Apache or IIS is serving up the page. 

Applying the lessons of the web to applications, you come up with something quite a lot like Web 
services. The beauty of Web services is its brutal simplicity, which squashes everything down to 
a lowest common denominator. A Web services architecture doesn't care about the benefits of any 
particular platform, and it doesn't care about the pitfalls. Those are your problems. All that matters 
to the outside world is that a program can send and receive text messages across HTTP or SMTP and 
that these text messages can trigger computational actions. 

An archetypal Web service would be something like a Japanese-to-English translation service. It 
lives somewhere on the Internet, on some unknown platform, and is written in some unknown pro- 
gramming language. You don't need to know or care about that stuff. All you care about is that your 
browser or your mail client knows that you only read English — so every time you get a web page or 
an e-mail in Japanese, these applications automatically send their contents to this translation service 
and then display the translated results to you. You don't ever see or care that part of the processing 
is happening at some remote location — to you, the end user, it just looks as though your applica- 
tion is handling it seamlessly. Instead of your web browser using Babelfish to translate Japanese 
to English and your mail client having a little built-in dictionary and your local department store's 
inventory management system using a third-party program that runs only on Solaris — all of them 
can just call this translation Web service. 
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Web services should also enable much easier integration. Say that you work for a university alumni 
office that is still using an alumni database written in COBOL on a VAX. (You may laugh, but Y2K 
wouldn't have been such a big deal if there weren't so many legacy systems lying around.) It works 
perfectly well, and you don't have budget to replace it — but those VAX terminals are getting old. It 
would sure be great if you could query your alumni database via an ordinary web browser — but 
there's no way you're ever going to be able to squeeze a full web server onto that old VAX, even if 
someone wrote one. With Web services, if you can get the VAX to understand just a little bit of XML 
and spit out its data as XML, you're all set. You can exchange instructions and data via XML by using 
some other machine that does have a web server, and that other machine can communicate with the 
rest of the world. Someday when you are ready to replace that VAX with a newer machine and a dif- 
ferent programming language, no one need ever know. As long as the service is reachable at the same 
address by using the same method invocations, it doesn't matter whether it's a VAX or a PC, whether 
the application was written in COBOL or whether it's just a thin shell of PHP on top of a database. 

Integration between businesses particularly benefits the smaller parties involved. Web services are 
easy to implement because corporate firewalls already have holes punched through them for HTTP 
and SMTP and because they can be implemented by using inexpensive software such as PHP. Say 
that you run a small business that makes widgets. You want your widgets distributed by a large 
retailer, Humongous Widget Depot. Until recently, for you (and the gazillions of other manufactur- 
ers who supply goods to Humongous Widget Depot) to provide real-time inventory information to 
the retailer entailed tremendous expense as you bought a large software package such as SAP and 
integrated it on a private network. Now, in theory, each small manufacturer can merely expose its 
inventory information via a Web service, and Humongous Widget Depot's humongous IT depart- 
ment merely points a Web services client at them. 

That, in a nutshell, is the dream and the promise of Web services. We are quite a way from the actu- 
ality, but the outlines of a solution are firming up. 



REST, XML-RPC, SOAP, .NET 

For Web services to work, every application and many servers need to speak a common language. 
Everyone agrees that the common language is XML, but there are some philosophical differences 
about the implementation details. The three main Web services standards are REST, XML-RPC, and 
SOAP. One of the biggest backers of SOAP is Microsoft, which uses that standard heavily in its .NET 
services architecture. 



REST 

REST is an acronym for REpresentational State Transfer. The concept is based on a dissertation by 
Roy Fielding, and its main point is that we already have everything we need to implement Web ser- 
vices — in HTTP itself. For all intents and purposes, a REST service is just an XML page on the web, 
although usually not one that is intended to be read by a human being using a browser. 
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REST is particularly valuable for content-focused services. You can build an XML document on the fly, 
and your users can access it reliably as a URI. In theory, REST should also be easier for lightly technical 
users to deal with. On the other hand, REST doesn't have built-in support for complex types — because 
there's no shared vocabulary, there's no particular way to designate an array versus a string. 

You can learn more about REST at the RESTWiki: 

http://rest.blueoxen.net/cgi-bin/wiki.pl 

XML-RPC refers to a spec for making remote procedure calls over HTTP by using XML encoding. An 
XML-RPC server takes an input that consists of a simple XML encoding of a method call sent as an 
HTTP POST. An example is: 

POST /xml rpc-epi /xml rpc-php-epi /sampl e/server . php HTTP/1.0 
User-Agent: xml rpc-epi -php/0 . 2 (PHP) 
Host: localhost:80 
Content-Type: text/xml 
Content- Length : 191 

<?xml versi on= ' 1 . 0 ' encodi ng= ' i so-8859-1 ' ?> 
<methodCal 1 > 

<methodName>greeti ng</methodName> 
<pa rams> 
<pa ram> 
<val ue> 

<string>World</ string) 
</val ue> 
</param> 
</pa rams> 
</methodCal 1 > 

Assume that greeting()isa function that takes a string input and returns a string output consist- 
ing of the string "Hello, " prepended to the input string. It returns a response that is formatted in a 
similar way. An example is: 

<?xml versi on= ' 1 . 0 ' encodi ng= ' i so-8859- 1 ' ?> 
<methodResponse> 
<pa rams> 
<param> 
<val ue> 
<a rray > 
<data> 
<va 1 ue> 

<string>Hello, World</string> 
</val ue> 
</data> 
</array> 
</val ue> 
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</pa ram> 
</params> 
</methodCal 1 > 

Notice that unlike using REST, you are not simply asking for data back — you are calling a specific 
function on another machine using specified types. This particular function happens to simply 
return data, but that is entirely arbitrary — any method the server owner is willing to expose as a 
Web service is fair game. Also unlike REST, XML-RPC supports all PHP native types, except objects 
and resources, and also a few that PHP doesn't have (structs, date-time, base-64 binary). 

XML-RPC can be seen as a compromise between the complexity of SOAP and the simplicity of 
REST. It is so similar to SOAP, however, that it may simply be absorbed wholesale into the more 
vendor-friendly concept. As you will see, the PHP XML-RPC server can also deliver SOAP responses. 

Learn more about XML-RPC at www .xmlrpc.org. 

SOAP 

SOAP may or may not stand for Simple Object Access Protocol — some members of the committee 
dispute this — but so many people have said it now that it's become true through usage. SOAP is 
a proposal of the W3C. SOAP, like XML-RPC, sends messages in XML wrappers with a fairly strict 
vocabulary that makes extensive use of namespaces. A very simple SOAP request may look like this: 

POST /xml rpc-epi /xml rpc-php-epi /sampl e/server . php HTTP/1.0 
User-Agent: xml rpc-epi -php/0 . 2 (PHP) 
Host: localhost:80 
Content-Type: text/xml 
Content- Length : 530 

<?xml vers i on= ' 1 . 0 ' encodi ng= ' ' i so-8859-1 ' ?> 

<SOAP-ENV:Envelope 

xmlns:SOAP-ENV="http://schemas.xm lsoap.org/soap/envelope/" 
xmlns:xsi="http:/ /www . w3 . org/ 1999/XMLSchema -instance" 
xmlns:xsd="http:/ /www .w3.org/1999/XMLSchema"> 

<SOAP-ENV:Header> 

</SOAP-ENV:Header> 
<SOAP-ENV:Body> 

<greeti ng> 

<xsd:string>World</xsd: string) 

</greeti ng> 
</SOAP-ENV:Body> 
</SOAP-ENV:Envelope> 

The response may be something like the following: 

<?xml vers i on= ' 1 . 0 ' encodi ng= ' i so-8859-1 ' ?> 
<S0AP-ENV: Envel ope 
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xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xml ns : xsi =" http : //www .w3.org/1999/XMLSchema-instance" 
xmlns:xsd="http: //www .w3.org/1999/XMLSchema"> 
<SOAP-ENV:Header> 

</SOAP-ENV:Header> 
<SOAP-ENV:Body> 
<greetingResponse> 
<SOAP-ENC:Array SOAP 
<xsd : stri ng>Hel 1 o , 
</SOAP-ENC: Array) 
</ greeting Response) 
</SOAP-ENV:Body> 
</SOAP-ENV:Envelope> 

SOAP offers you even more data types than XML-RPC. You must, however, specify a lot more, too. 
Other than that, the two protocols are very similar. Obviously, SOAP also enjoys greater acceptance 
from Big Software. 

Learn more about SOAP at www .soapware.org/bdg. 



Current Issues with Web Services 

By now, you're probably thinking, "Okay, if Web services are so great, why aren't we using them 
everywhere?" Well, there are still many issues to be worked out. Web services are in their infancy, 
and it is likely to be years before we live in a totally Web-serviced world. 

Large Footprint 

Web services can be rather data-intensive and heavy in terms of wrappings and protocol, even for 
simple calls. This drives binary programmers especially crazy, accustomed as they are to apps talk- 
ing to each other in compact binary formats. To a large extent, people just need to get over this, but 
there are still many situations where data storage, memory, and bandwidth are issues — in cellular 
phones, for instance. 

Potentially heavy load 

So far, there is no standard way to cache the results of RPC calls. Even if 80 percent of your clients 
are asking for the exact same response and, therefore, you can't save resources — every request must 
handled de novo. 

REST enables caching via all the methods by which HTML can be cached. 



-ENC: array Type="xsd:string[l]"> 
worl d</xsd : stri ng> 



681 



Part V 



Connections 



Standards 

Before Web services can really take off, applications need to handle their results transparently. 
Because the Web services standards are still somewhat in flux, and there are multiple candidates 
with competing strengths, this has not yet happened. For smallish web applications, it's not that 
big a deal if some service changes one of its API methods — but for a big app like Lotus Notes, it's a 
major investment of resources to transparently deal with SOAP. 

The companies that are leading the way in public Web services — Amazon, Salesforce.com, eBay, 
and Google — have so far used a mixture of Web service APIs. Many of them maintain multiple 
interfaces for developer convenience; Amazon, for instance, offers all its Web services via both REST 
and SOAP. While this is extremely developer-friendly of them, in the long run most organizations 
long for a single, stable standard to conform to. 

Hide and seek 

The ultimate goal of Web services is to have the application transparently find all the resources 
it needs. Say that you get an e-mail in Japanese — your mail server or client should be smart 
enough to find the translation service it needs, get your document translated, and show the final 
result to you. 

To accomplish this, we need some kind of directory system and a standard way for servers to 
describe themselves. WSDL and UDDI are the technologies that can make this possible. WSDL 
(Web Services Description Language) describes a Web service interface, while UDDI (Universal 
Description, Discovery, and Integration) is a registry for Web services. Learn more about UDDI and 
WSDL, respectively, at http://uddi . xml .org and www .w3.org/TR/wsdl. 

We are a long way, however, from automatic discovery and communication by applications. In fact, 
many businesses that deploy Web services deliberately do so under a veil — for example, FedEx, 
which needed to take down its public SOAP server after it was used for fraud by crackers. Web ser- 
vices are growing most quickly in the realm of semiprivate transactions — companies set up Web 
services that are only meant to be accessed by authenticated and authorized business partners. 

Who pays and how? 

Ultimately, the biggest question about public Web services is: Who pays for them, and how? So far 
most of the Web services that you can access are things such as weblog entries and simple currency 
calculators — services for which you normally would not expect to pay. Big Software's answer is to 
create huge private networks of Web services, similar to those of Hailstorm or the Liberty Alliance. 
This has serious implications for privacy and open architecture. 

Unless and until Web services find a way to pay for themselves, they are likely to continue to be 
deployed mostly inside corporate firewalls and in nonprofit situations. 
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Project: A REST Client 

Listing 41-1 is a basic client script for Amazon's elegantly simple REST service, which has been avail- 
able (with some changes) to Amazon Associates and other developers since spring of 2002. You feed 
the script a search string at the top, and it outputs a CSS-formatted box at the end containing infor- 
mation about the current edition of the book in question. 

This service clearly demonstrates the biggest advantage of REST: You can work with it by using the 
HTTP concepts — and the PHP functions — you're already familiar with. For all intents and pur- 
poses, you are simply asking for a web page by using http f open ( ) . It happens to be well-formed 
XML instead of HTML — but that is incidental to the transport mechanism. 

We chose to parse the XML by using PHP's DOM XML extension, which so far has found relatively 
few real-world uses (see Chapter 40 for discussion of the DOM). Many other PHP-literate Amazon 
developers have produced scripts that use other types of parsing, such as string parsing and regex, 
to extract the desired information — but we want to show you the power of using XML itself. 

We should warn you, however, that this type of solution does not scale — DOM XML is a notorious 
memory hog. (We've heard credible reports that a 1,000-line XML document read into the DOM 
results in 1MB of memory being appropriated.) However, the Amazon Web services interface will 
only return a few items at a time, so DOM XML is an appropriate technology for this purpose. 

' i' : ' The DOM extension changed significantly in PHP5. This script will not work at all in ver- 
sions of PHP before 5.0.0b2. Obviously, the script will also not work unless you have pre- 
viously compiled PHP with the with domxml flag and Iibxml2. 



LISTING 41-1 



Client for Amazon RESTservice (rest_amazon_client.php) 

<?php 

// Get the xml 

$writefile = ' mysql bi bl e . xml ' ; 

$f i 1 e = "http://ecs.amazonaws.com/onca/xml7Servi ce=AWSECommerceServi ce&AWSAcce 
ssKeyId=XXXXXXXXXXXXXXXX&0peration=ItemLookup&IdType=ASIN&ItemId=0764549324&Ve 
rsion=2008-04-07&ResponseGroup=Medium,0fferFull"; 

$f p = f open ( $f i 1 e , " r" ) ; 
$xml_array = file($file); 
fclose($fp) ; 

$xml_str = implode("", $xml_array); 
$fp2 = f open ( $wri tef i 1 e , "w"); 
$fw_return = fwn'te($fp2, $xml_str); 
fclose($fp2) ; 

$xml = f i 1 e_get_contents ( $wri tef i 1 e ) ; 
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$1 oaded_xml = s i mpl exml_J oad_stri ng ( $xml ) ; 

// Load up the xml file into memory 

$dom = new DomDocument; 

if ( ! $dom->l oad( $wri tef i 1 e) ) { 

echo "Cannot load XML file"; 

exi t ; 

} 

// Get an immediately available edition 

$asin = $1 oaded_xml ->Items->Item->ASIN ; 

$url = $1 oaded_xml ->Items->Item->Detai 1 PageURL; 

$title = $1 oaded_xml ->Items->Item->ItemAttri butes->Ti tl e ; 

Simageurl = $1 oaded_xml ->Items->Item->Medi umImage->URL; 

// Format a nice box 

$box_str = <<< EONICEBOX 

<HTML> 

<HEAD> 

<STYLE> 

#c on tent ( 

float: left; 

padding: lOpx; 

margin: lOpx; 

background: #FFFFFF; 

border: 4px solid #008000; 

width: 200px; /* ie5win fudge begins */ 

voi ce-f ami 1 y : " \ " ) \ " " ; 

voi ce-f ami 1 y : i nheri t ; 

width: 200px; 

} 

html>body #content { 

width: 170px; /* ie5win fudge ends */ 
} 

P ( 

font-family: Verdana, Arial, sans-serif; 
font-size: 12px; 
line-height: 22 px; 
margin-top: 3px; 
margin-bottom: 2px; 

} 

</STYLE> 

</HEAD> 

<B0DY> 

<div id=" content "> 

< p >< i mg s r c = " $ i ma g e u r 1 " > 

<BRXA HREF="$url ">$title</A> 

</p> 
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</B0DY> 
</HTML> 
EONICEBOX; 
echo $box_str; 
?> 



Those of you who do not have Amazon Associates accounts can use Listing 41-2 for testing, which 
you should save as mysql bible, xml somewhere under your web tree. 



LISTING 41-2 



XML sample (mysqlbible.xml) 

<?xml versi on="l . 0" ?> 

< I temLookup Response xmlns="http://webservices.amazon.com/ 

AWSECommerceService/2008-04-07"> 

<0perati on Request) 

<RequestId>15409f90-7eca-4743-90e2-c7 76913b4e6c</RequestId> 
<Arguments> 

<Argument Name="0perati on" Val ue=" ItemLookup"X/Argument> 
<Argument Name="Servi ce" Val ue="AWSECommerceServi ce"X/Argument> 
<Argument Name=" Vers i on " Val ue="2008-04-07"X/Argument> 
<Argument Name=" Itemld" Val ue="0764549324"X/Argument> 
<Argument Name=" IdType" Val ue="ASIN"X/Argument> 
<Argument Name="AWSAccessKey Id" Va 1 ue= " XXXX " X/Argument> 
<Argument Name="ResponseGroup" Value="Medium,OfferFull "X/Argument> 
</Arguments> 

<Request Process i ngTi me>0 . 024584000000000CK/ Request Process i ngTi me> 

</OperationRequest> 

<Items> 

<Request> 

<I sVal id>True</IsVal id> 

< I temLookup Request> 

<Condition>New</Condition> 

<DeliveryMethod>Ship</Deli very Method) 

<IdType>ASIN</IdType> 

<MerchantId>Amazon</MerchantId> 

<0fferPage>K/0fferPage> 

<ltemld>0764549324</ltemld> 

<ResponseGroup>Medium</ResponseGroup> 

<ResponseGroup>OfferFull</ResponseGroup> 

<ReviewPage>K/ReviewPage> 

<ReviewSort>-SubmissionDate</ReviewSort> 

<VariationPage>All</VariationPage> 

< / It em Lookup Request> 
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</ Request> 
<Item> 

<ASIN>0764549324</ASIN> 

<Detai 1 PageURL>http : //www . amazon . com/My SQL- Bi bl e-CDROM- Steve - Suehri ng/dp/07645 
49324%3FSubscriptionId%3D03S5FBC8SMHRV9HBDWG2%26tag%3Dws%261 inkCode%3Dxm2%26ca 
mp%3D2025%26creati ve%3D165953%26creati veASIN%3D0764549324</Detai 1 PageURL> 
<Sal esRank>7807 53</Sal esRank> 

<SmallImageXURL>http://ecx.images-amazon.com/images/I/51WJRNR4ENL._SL75_. 
jpg</URLXHeight Uni ts = " pi xel s " > 7 5 < / H e i ghtXWi dth Uni ts = "pi xel s ">60</Wi dth></ 
Smal 1 Image) 

<MediumImage><URL>http://ecx.i mages -amazon. com/i mages/ I /51WJRNR4ENL._SL160_. 
jpg</URLXHeight Uni ts = " pi xel s " >160</Hei ghtXWi dth Units="pixel s">128</ 
WidthX/MediumImage> 

<LargeImage><URL>http://ecx.images-amazon.com/images/I/51WJRNR4ENL.jpg</ 
URLXHeight Uni ts = " pi xel s " >47 5</ He i ghtXWi dth Uni ts = "pi xel s " >380</Wi dt h></ 
La rge Image) 
<ImageSets> 

<ImageSet Category ="pri ma ry"XSwatchImageXURL>http://ecx. images - amazon. com/ 

images/ I /51WJRNR4ENL._SL30_. jpg< /URLXHeight Uni ts = " pi xel s " >30</Hei ghtXWi dth 

Units = "pixels">24</WidthX/SwatchImageXSmallImageXURL>http://ecx.images- 

amazon .com/ images/ 1 /51WJ RNR4EN L ._S L7 5_. j pg</URLXHei ght Uni ts = " pi xel s " >7 5</ 

Hei ghtXWi dth Uni ts = " pi xel s " >60</Wi dthX/Smal 1 ImageXThumbnai 1 ImageXURL> 

http : //ecx . images -amazon . com/i mages/ 1 /51WJRNR4ENL ._SL75_. jpg</URLXHei ght 

Un i ts = " pi xel s">75</ Hei ghtXWi dth Uni ts="pi xel s " >60</Wi dthX/Thumbnai 1 ImageXT 

inyImageXURL>http://ecx.images-amazon.com/images/I/51WJRNR4ENL.__SL110_.jpg</ 

URLXHeight Uni ts = " pi xel s " >1 1 0 < / H e i ghtXWi dth Uni ts = "pi xel s " >88</Wi dthX/Ti n 

yImageXMediumImageXURL>http: / /ecx. images - amazon. com/ images / 1 / 51WJRNR4 EN L._ 

SL160_.jpg</ URLXHeight Uni ts=" pi xel s " >160</Hei ghtXWi dth Uni ts="pi xel s " >128</ 

W i dthX /Med iumlmageX La rgeImage><URL>http:/ /ecx. images -amazon. com/ 

images/I/51WJRNR4ENL.jpg</URLXHeight Uni ts = " pi xel s " >475</ Hei ghtXWi dth 

Un i ts= " pi xel s">380</Width></ Large Image) 

</ ImageSet) 

</ ImageSets> 

<ItemAttri butes> 

<Author>Steve Suehri ng</Author> 

<Binding>Paperback</Binding> 

< Dewey Deci ma lNumber>005.7 565</DeweyDecimal Number> 

<EAN>9780764549328</EAN> 

<Edition>Pap/Cdr</Edition> 

<ISBN>0764549324</ISBN> 

<Label >Wi 1 ey</Label > 

<Languages><LanguageXName>English</NameXType>Original Language</TypeX/Langu 

age><LanguageXName>Engli sh</NameXType>Unknown</Type></LanguageXLanguage><Na 

me > Engl i s h< / Na me XType>Published</TypeX/Language>< / Languages) 

<Li stPri ceXAmount>4999</AmountXCurrencyCode>USD</CurrencyCodeX Forma ttedPri c 

e> $49. 99</ Forma ttedPri ceX/Li stPri ce> 

<Manufacturer>Wiley</Manufacturer> 

<NumberOf Items) K/NumberOf I terns > 

<NumberOf Pages>77 5</Number0f Pages> 
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<PackageDimensionsXHeight Units=" hundredths -inches">170</Height><Length 

units = " hundredths- inches ">920</LengthXWeight Un its = " hundredths- pounds ">240</ 

WeightXWidth Units=" hundredths- inches">770</Width></PackageDimensions> 

<ProductGroup>Book</ProductGroup> 

<ProductTypeName>ABIS_BOOK</ProductTypeNatrie> 

<Publ icationDate>2002-06-15</Publ icationDate) 

<Publisher>Wiley</Publisher> 

<Studio>Wiley</Studio> 

<Title>MySQL Bible with CDR0M</Ti tl e> 

< / 1 temAttri butesX/ItemX/ItemsX/It em Lookup Response) 



The result of the REST client script is shown in Figure 41-1. 



FIGURE 41-1 



REST client gets XM1 and outputs HTML 
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As you can see from the XML sample, there is a lot of potential data from the Web service that we 
didn't use — suggested price, release date, and so on. This demonstrates how easy it is to pick out 
just the data you want from the feed using Simple XML. According to the current Amazon Web ser- 
vices rules, you could poll its Web service for fresh XML every second, so you could keep this part 
of your information very fresh. 
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Summary 



Web services is an emerging field of programming. Web services offer immediate payoffs in data 
transfer, especially for web applications, and may finally unlock the promise of distributed com- 
puting. Although there is a lot of hype and misinformation out there about the technologies, and 
although much of the action is happening inside intranets and in semiprivate transactions, you can 
start familiarizing yourself with PHP to both create and consume Web services. 

The three main Web services standards in discussion now are REST, XML-RPC, and SOAP. REST is 
the most lightweight and easy to use but offers the least functionality. SOAP is the most complicated 
and, as a consequence, has the most interoperability problems, but large vendors such as Microsoft 
and IBM have thrown their support behind it. XML-RPC offers a nice blend of power and simplicity 
but lacks big-vendor support. 

PHP can be used to create servers and clients in REST, XML-RPC, and SOAP. However, particularly 
with SOAP, the syntax is so complex that a third-party package may be highly useful for help with 
the serialization, type-shuffling, and request-creation steps required by Web services. 
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In this chapter, we delve into how to use PHP to create graphics of 
your own and display them to the user. Although we spend a little 
bit of time on pure HTML "graphics," our primary focus is on creat- 
ing images on the fly by using the gd library. This library helps you create 
images such as PNGs and JPEGs, which you can then link to from dynami- 
cally generated HTML pages or send to the user as standalone web pages. 



Your Options 



Just to see where image creation fits into the web-scripting world, look at 
the following spectrum of choices, in order of increasing dynamics: 

■ You can have no graphics at all and display purely textual 
information. 

■ You can embed static images in your HTML, whether created by 
yourself or by other people. 

■ You can write programmatically generated HTML 
pseudographics. 

■ You can embed static image graphics (or even image animations, 
if you insist) in your HTML pages, but display different ones 
conditionally. 

■ You can use gd to pre -generate static graphics for all the cases that 
may possibly arise from your code, store them in files, and display 
them conditionally. 

■ You can create graphic images on demand in response to user input. 



IN THIS CHAPTER 



Overview of images in web 
scripting 

Creating graphics in HTML 

Introduction to the gd image 
manipulation library 

Troubleshooting image creation 
code 
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We start off with the third option (HTML graphics) and then devote most of the rest of the chapter 
to the last one, which is the most interesting case. 



HTML Graphics 

You know those horizontal, colored bar graphs you see all over the web, especially in connection 
with poll results? It looks as though some graphics are being used in creating these graphs, but in 
truth there're just a couple of canned color images and the magic of image scaling in HTML. This 
graphing technique is actually very useful, and we include it here because it's very easy to create 
graphs like this dynamically from PHP. 

Before we get into this data visualization technique, we need some data. Listing 42-1 shows a small 
sample data set, which we imagine has been produced from a survey of programmers asked about 
their favorite languages and operating systems. The data is stored in a MySQL database, in a single 
table, with the following definition: 

CREATE TABLE programmers ( 

id int(ll) NOT NULL auto_i ncrement , 
sex chard) default NULL, 
age int(ll) default NULL, 
language varcharOO) default NULL, 
os varcharOO) default NULL, 
country varcharOO) default NULL, 
continent varcharOO) default NULL, 
PRIMARY KEY (id) 

); 



LISTING 42-1 



Sample data set 



H V- 



|id|sex|age| language | os 



country 



conti nent 



H V h- 



1 1 


F 


| 33 


PHP 


Li nux 


USA 


| North America 


2 


M 


41 


Java 


Sol a ri s 


USA 


| North America 


4 


M 


31 


C++ 


Sol a ri s 


USA 


| North America 


5 


M 


45 


Lisp 


MacOS 


USA 


| North America 


6 


M 


25 


C 


Sol a ri s 


Antarcti ca 


| Antarctica 


7 


F 


17 


PHP 


Li nux 


Denma rk 


j Europe 


8 


M 


21 


Perl 


Li nux 


UK 


j Europe 


9 


M 


14 


PHP 


Li nux 


UK 


j Europe 


10 


F 


21 


Perl 


Li nux 


Germany 


j Europe 
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11 


F 


38 


PHP 


Li nux 


Germany 


Europe 


12 


M 


26 


C++ 


Wi ndows 


USA 


North America 


13 


M 


22 


PHP 


Wi ndows 


France 


Europe 


14 


M 


17 


PHP 


Li nux 


Japan 


Asi a 


15 


F 


38 


C 


Solaris 


South Korea 


Asi a 


16 


F 


19 


PHP 


Li nux 


Canada 


North America 


17 


F 


32 


Perl 


Li nux 


France 


Europe 


18 


M 


32 


Java 


Solaris 


Mexi co 


North America 


19 


F 


23 


PHP 


Solaris 


Brazil 


South America 


20 


F 


19 


PHP 


Li nux 


Finland 


Europe 


21 


M 


21 


PHP 


Li nux 


Brazil 


South America 


22 


M 


51 


Java 


Li nux 


UK 


Europe 


23 


M 


29 


Java 


Li nux 


Japan 


Asi a 


24 


M 


29 


Java 


Solaris 


China 


Asi a 


25 


M 


21 


C++ 


MacOS 


Germany 


Europe 


26 


M 


21 


Perl 


Solaris 


France 


Europe 


27 


M 


27 


PHP 


Li nux 


India 


Asi a 


28 


M 


31 


Perl 


Li nux 


India 


Asi a 


29 


M 


17 


C 


Li nux 


Pakistan 


Asi a 


30 


M 


45 


PHP 


Wi ndows 


USA 


North America 


31 


F 


22 


Java 


Wi ndows 


Italy 


Europe 


32 


F 


33 


C 


Li nux 


Spain 


Europe 



So say that our goal is to visualize counts of the distribution of values for different columns — we 
want to know not only how many of our respondents list this or that programming language, but 
also to see comparisons graphically. 

Although our data is in a MySQL database, the display portion of this code need not be tied to that. 
We may want to use it for a different purpose entirely. So we break out a separate function that pro- 
duces a bar graph from an array in a particular format, and only later hook that up to code that pro- 
duces the requisite array via SQL queries. The code to translate an array into a bar graph is shown in 
Listing 42-2. 



LISTING 42-2 



bar_graph.php 

<?php 

function array_to_bar_graph ($array, $max_width) I 
// expects as input an array where the keys 
// are string labels and the values are 
II numbers. Values must be non-negative 
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// returns an HTML bar graph as a string 
// assumes bar [1-5] . gi f , located in images/ 

foreach ($array as lvalue) ( 
if ((IsSet($max_value) && 

(lvalue > $max_value)) | 
( ! IsSet($max_val ue) ) ) ( 
$max_val ue = $val ue ; 

1 

) 

Spixel s„per„val ue = ((double) $max_width) 
/ $max_value; 



$string_to_return = "<TABLE C E L LPADD I N G=5 > " ; 
Scounter = 0; 

foreach ($array as $name => lvalue) { 
$bar_width = lvalue * $pi xel s_per_val ue ; 
$image_no = (Scounter % 5) + 1; 
$stri ng„to_return . = 
"<TRXTD>$name ($value)</TD> 
<TDXIMG SRC=\ "images /bar$image_no.gif\" 
WIDTH=$bar_width 
HEIGHT=10> 
</TDX/TR>" ; 
$counter++; 

) 

$ s t r i ng_to_return .= "</TABLE>"; 
return ( $stri ng„to_return ) ; 

} 

?> 



The bar graph code is extremely simple — it iterates through an array, which is assumed to have 
names for keys and quantities for values. It normalizes the maximum value to a fixed-width bar and 
calculates the width of all the other bars proportionally. Finally, it displays bars by using the scaling 
parameters in the < I MG> tag to give each variable a fixed height and an appropriate width. It cycles 
through a list of five images, which are premade one-color GIFs (which could as well be PNGs) and 
could be created by using your favorite graphics program. As long as these images are monocolor, 
their size and shape are irrelevant. (If you don't have any such images handy, you can find the ones 
we used at the code download site: www . troutworks . com/phpbook.) 

Now that we can display names and associated values in a bar graph, we can hook that up to the 
database via a Web form and an SQL query. Code for this is shown in Listing 42-3. 
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LISTING 42-3 



bar_graph_form.php 

<?php 

include_once("dbconnect.inc"); 
i n c 1 u d e_o n c e ( " b a r_g r a p h . p h p " ) ; 
mysql_connect ( $hostname , $user, $password); 
mysql_sel ect_db( "c43" ) ; 

if (IsSet($_POST['COLUMN_NAME'])) { 

$col umn_name = mysql_real_escape_stri ng( $_POST[ 1 COLUMN_NAME ' ] ) ; 
$query = "select $col umn_name , count(*) 
from programmers 
group by $col umnjame" ; 
$result = mysql_query ( $query ) 

or die("Error in database i nteracti on<BR>" . 
mysql_error( ) ) ; 
$array_col 1 ecti on = array(); 
while ($row = mysql _f etch_row( $ resul t ) ) { 
$name = $row[0] ; 
Icount = $row[l] ; 

$array_col 1 ecti on[$name] = $count; 

) 

$bar_graph = 

a rray_to_ba r_graph ( $a rray_col lection, 
300) ; 

} 

else ( 

$bar_graph = " " ; 



$self = "bar_graph_form.php" ; 
$form = <<<E0T 

<F0RM METH0D=P0ST ACTI0N=" $sel f "> 

<H3>Choose a table column for graphi ng</H3> 

<SELECT NAME=COLUMN_NAME> 

<0PTI0N VALUE=os>os 

<0PTI0N VALUE=1 anguage>l anguage 

<0PTI0N VALUE=continent>continent 

<0PTI0N VALUE=sex>sex 

</SELECT> 

<I NPUT TYPE=SUBMIT NAME=SUBMIT> 

</F0RM> 

EOT; 

$page = <<<E0T 

<HTMLXHEADXTITLE>Survey data</TITLEX/HEAD> 
<B0DY> 
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$f orm 
<BR> 

$bar_graph 

</BODYX/HTML> 

EOT; 

echo $page; 
?> 



The form is self-submitting and loads a file called dbconnect.inc, which contains the appropriate 
login, password, and database name, like this: 

<?php 

$hostname = "YOURMYSQLHOST" ; 
$user = "YOURMYSQLUSER" ; 
$password = "YOURMYSQLPASSWORD" ; 
?> 

All that is supplied by the form submission is the name of the column. Starting with that, the code 
submits an SQL statement to count all the distinct values that occur for that column and then cre- 
ates an array by using names and the corresponding counts. What remains is to feed the resulting 
array to the bar graph code from Listing 42-1 and to do some layout. The results for two different 
columns are shown in Figures 42-1 and 42-2. (Since this is a grayscale book, you won't see interest- 
ingly different colors in the diagram, but you should at least see bars of different sizes.) 



FIGURE 42-1 



HTML bar graph 1 



Survey (J,iM - Morill,! (Build ID: 2002051006] 


Mill 


„ File Edit View Co Bookmarks Tools Window Help D_ebug QA 


(3^ £5 £J O 1%. hnnLf/192. 168.1 .l/graphic* | [<\ Snatch | 




Choose st tabic column for papliiiig 




| os Su bmit Query | 




MacOS (2) ^ m 
"Windows (4) 




Document: Done (1.32 sees) 
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HTML bar graph 2 



Survey data f.Will.i (Build ID; 20020510061 






„ File Edil View £o Bookmarks Tools Window Help 


Debug QA 




Qi \''- htlo:ff192. 168.1. 1/graphirs [|-\$aaich| 




Choose a tabic column Tor grapliing 






| language zl Submit Query | 












C++ (3) 












Lispd) ™ 


















Do aimem: Done (0.82 sees) 




-J- Li' 



Creating images using gd 

Having mostly exhausted the graphic possibilities afforded by vanilla HTML, let's turn our attention 
to creating real standalone graphics by using the gd library. 

What is gd? 

What is gd, anyway? The gd toolkit is a C code library for creating and manipulating images, which 
was originally created by the kind and clever people at Boutell.com (www . boutel 1 . com), gd is not 
a graphics or paint program in and of itself, as it has no standalone application or GUI. Instead, it 
provides functions that programs can call to do these manipulations, and any C program that wants 
to can link against that library to use the routines. The PHP developers have done this and, in fact, 
have written a set of interface functions that make it easy to call gd routines from PHP. But nothing 
in gd is specific to PHP, and there are interfaces to it from several other languages and environ- 
ments, including Perl, Tel, Pascal, Haskell, and REXX. 

gd lets you call functions to create images (initially blank, like a clean sheet of paper), draw and 
paint on those images in various ways, and ultimately convert the image from gd's internal image 
format to a standard image format, and send it off to its ultimate fate (display in a browser or storage 
in a file or database). And because all this is under programmatic control rather than human control, 
these created images can be arbitrarily complex, and they can depend on anything in your program 
that you would like to have them depend on. 
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Image formats and browsers 

The gd library can, in principle, import and output images in a wide variety of formats. The three 
image formats we talk about at all seriously are GIF, JPEG, and PNG, although for examples we focus 
mostly on the last of these. 

The GIF and PNG formats essentially exist to describe a grid of colored cells corresponding to pix- 
els, with a few complications. The first complication is that the cells may contain actual color values 
or they may contain indexes in a table of color values. (The former is more expressive because any 
number of different colors may be used, and the latter is more compact.) 

Another complication is that, although the conceptual representation of GIFs and PNGs is fairly 
simple, in practice they are always read, written, and transferred in compressed form. Compression 
is necessary because a grid of cells is a costly thing to specify. A simple 500 X 400 pixel image is 
200,000 pixels — if each pixel needs 3 bytes to specify, then we're over half a megabyte already. 
Compression is a large topic, but most compression algorithms take advantage of redundancy in the 
image to make it smaller. (There are more concise ways to say that every pixel is green than specify- 
ing every pixel's green color value individually.) Unfortunately, there is a lot more to compression 
algorithms than that — enough so that the compression algorithm used for writing GIFs is patented. 

Early browsers were written using GIF as the graphics format of choice, and it wasn't until that practice 
had been under way for a while that it became clear that the patent holder was going to insist on going 
after people who used the compression algorithm. This left web graphics in a bit of a bind — GIF was 
the lingua franca, but you couldn't legally create such graphics, at least without paying a license fee. 
The PNG format has come to the rescue in a sense — recent versions of major browsers support it, and 
with that support it plays much the same role as GIF. 

Compression is different in the case of JPEGs, as well, although not for legal reasons. Compression 
for GIFs and PNGs is lossless, meaning that if you compress and then uncompress an image, you 
should have your exact original image back. The JPEG compression, on the other hand, is lossy. 
Essentially, if redundancy helps compression, JPEG compression tries to introduce a little bit of extra 
redundancy into the image before compression, mostly in ways that the human eye won't notice. 
This is particularly effective with photographic images, but it does mean that sometimes the com- 
pression/uncompression cycle doesn't leave you with exactly what you started with. 

Because JPEG is better for photographic images than the kinds of images we're making, and because 
deciding on the export format is a final step anyway, we've decided to focus on PNG graphics 
exclusively. If you would rather produce JPEGs, it is a simple matter to change the export functions 
appropriately. 

Installation 

Installing gd and getting it to work with PHP is, frankly, a pain. This is not because of any weakness 
in either the PHP codebase or the gd codebase but is all about configuration issues: sorting out the 
likely and actual locations of the libraries gd depends on and making sure that everything can build 
and link appropriately. So the happiest situation possible is to find out that gd is already installed, 
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and PHP already has gd support enabled (whether that's due to the diligence of your webhost or 
because the PHP you installed by yourself had it included). 

So the first step in installing gd is: Check to see if it has already been installed. Whether you are 
running via a webhost or are in command of your own installation, start off as always by putting the 
following into a file and viewing the result in a browser: 

<?php 

phpi nf o ( ) ; 

?> 

After you have the displayed page, just do a text search for gd in the browser window — you may 
find a subsection that describes to what extent gd is enabled in your PHP installation. If you only 
want to produce certain kinds of images (PNGs, for example) and phpi nf o( ) tells you that sup- 
port for that image type is enabled, then you may be good to go. If the gd version includes the word 
bundled, you are using the gd that is bundled with PHP. 

If this fails, and if you are in control of your PHP installation, you will have to install and configure 
gd. (If, instead, your PHP installation is run by a hosting company, your options may be reduced to 
asking them to provide gd support, or to switching webhosts.) 

Using the PHP-bundled version of gd removes some, but not all, of the hassle of a gd install; if 
you use the bundled version itself, you have the gd library but not necessarily the libraries that 
gd needs. The gd library itself depends on several other libraries: 1 i bpng (for manipulating PNG 
images), zl i b (used in compression), and jpeg-6b or later (if you want to manipulate JPEG 
images). (Only gd, 1 i bpng, and zl i b are necessary for the examples in this chapter.) These will 
be present already in many Linux installations, and if so it may be sufficient to include a wi th flag 
(such as - -wi th-zl i b) without specifying the installation directory. If you are configuring PHP 
yourself, adding the - -with-gd flag will cause the bundled version of g d to be included. Use 
--with-gd=path instead if you want to point to an alternate version. 

If you find that you lack one or more of the necessary libraries, you will have to build them. The 
documentation at www . 1 i bgd . org is a good place to start to find the current versions. 

gd Concepts 

While an image is being constructed or manipulated in the gd toolkit, it is stored in a gd-specific 
format that doesn't correspond to any conventional image type. Images can in theory be exported in 
this gd format, but it's unusual to do so because the resulting image is not compressed and cannot 
be displayed in a browser or conventional graphics program. 

An image in the gd toolkit has a width, a height, and color information for all the width x height 
many pixels. (See the "Colors" section for more detail on how colors are stored.) Usually a program 
starts off its interaction with gd by either creating a new blank image (which is drawn and painted 
on) or by importing an image from a file. The next steps are typically (1) allocate colors in the image, 
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(2) draw, paint, or otherwise transform the image, (3) translate the image to a conventional format 
(for example, PNG, JPEG), and send it to output. 

Colors 

There are two ways of representing colors in gd images: palette-based, which is limited to 256 colors, 
and truecolor, which can store an unlimited number of distinct RBG color values. In gd 1.x, palette- 
based colors were the only alternative; gd 2.x and the PHP-bundled version of it offers both palette- 
based images and truecolor images. Note that a given gd image is either palette-based or truecolor; 
there is no notion of adding true colors to a palette -based image. 

To get an initial blank palette-based image, you call the function ImageCreate();togeta truecolor 
image, call ImageCreateTrueCol or( ). 

Palette-based images 

Colors are specified in a red-green-blue (RGB) format, with three numbers between 0 and 255. The 
color specified by ( 2 5 5 , 0 , 0 ) , for example, is bright red; ( 0 , 255, 0 ) is green; ( 0 , 0 , 255) is 
blue; ( 0 , 0 , 0 ) is black; (255, 255, 255) is white; and (127, 127, 127) is gray. You can tweak 
these values to your heart's content to design new colors. 

Any drawing into an image must be done in a particular color, and colors must be allocated in an 
image before they are used. Also, the first color allocated into an image automatically becomes the 
background color. So, colors are not optional in any sense, and usually color allocation is the first 
thing you do after creating a new blank image. 

Colors in palette-based images are created by using imagecol oral 1 ocate( ), which takes as argu- 
ments an (already created) image, and three integers specifying the proportion of red, green, and 
blue. The return value is an integer, which specifies the index of the new color in the image's inter- 
nal palette. You must hang on to this return value in a variable, because you need the index value 
for any future drawing using that color. Palette-based images can have a maximum of 256 colors. (It 
may or may not be obvious what's going on under the hood here, but every pixel in a palette-based 
image is actually a single byte, which stores an index into the 256-color palette.) 

Note that the index returned by allocating a color in an image makes sense only for that image. If 
you assign an allocated color to the PHP variable $ b 1 a c k , it won't work to use that variable as the 
color input for a drawing command called on a different image. 

Truecolor 

In gd 2.0 and later, you can also create images that are not palette-based, where every pixel stores 
an arbitrary RGB color value. In this truecolor format, the number of colors is essentially unlimited. 
This can be useful not only for the free range of your artistic expression, but for faithfully represent- 
ing truecolor PNGs and JPEG images that have been loaded into gd. 

Aside from the initial function to create an image, and the lack of limitation on distinct colors, work- 
ing with truecolor images is similar to working with palette-based images. In particular, you still call 
ImageColorAllocateO to create new colors, and hang on to the return value for later commands 



698 



Creating Graphics with PHP 



to use; it just so happens that the returned value will be an RGB color rather than an index into a 
palette. Also, in truecolor images there is no notion of a background color created as a side effect of 
ImageCol orAl 1 ocate ( ) ; all pixels are initialized to black. 

Transparency 

gd 2.x supports transparency in the form of an alpha value (in addition to the red, green, blue values) 
that specifies how transparent the given color is. This allows you, for example, to overlay a shape 
onto another one without simply occluding the first shape. 

Many of the image functions in PHP have an analog with "alpha" in its name, which indicates that it 
deals with a four-value (R,G,B,A) color. For example, while ImageCol orAl 1 ocate( ) expects three 
arguments, ImageColorAllocateAlpha expects a fourth argument between 0 and 1 27. A value of 
zero indicates that the color is completely opaque; a value of 127 means that the color is completely 
transparent. 

Drawing coordinates and commands 

After you create an image within gd, you have an implicit coordinate system for drawing on it, 
determined by the width and height you specified. 

In this coordinate system, the origin (0, 0) is at the top-left corner of the image, and the positive 
direction for x values is to the right, whereas the positive direction fory values is down. (This is 
often true of computer graphics coordinate systems, but you may be more accustomed to a lower-left 
origin if you learned analytic geometry in school.) 

There are many drawing commands, including but not limited to drawing line segments, rectangles, 
arcs, and setting particular pixel values. Note that the end effect of all these painting and drawing 
commands is to set the value of pixels. There is no memory retained of the commands that changed 
the pixels and, therefore, no way to undo drawing commands or separate out the effects of distinct 
commands. 

Nothing stops you from drawing outside the bounds of the image you have specified, but such 
drawing has no visible effect. A rectangle with coordinate values that are all negative, for example, is 
not visible. 

Format translation 

All this drawing and image manipulation is done on the image in its gd -internal format. After your 
script is done, it can use one of the translation-and-output commands (imagetopng, imagetojpeg, 
and so on) to translate the image to the desired graphics format and echo it out to the user's browser 
(or to a file). 

Freeing resources 

After you have sent a translation of your completed gd image off to the user, you are done with the 
internal version and should dispose of it. The right way to do this is to call imagedestroy( ) with 
the image as an argument. 
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Functions 

We are not planning to individually list and describe all the functions in PHP's gd interface in this 
chapter; for that, we refer you to the "Image Processing and Generation" section of the manual at 
www .php.net. Here we summarize the most important functions. Most of the gd functions are in 
one of the categories shown in Table 42-1. Note that the function names in this table have internal 
capital letters at word breaks for clarity, but we may not always observe this when writing code 
because PHP function names are not case-sensitive. 



TABLE 42-1 



Breakdown of gd Functions 


Type 


Examples 




Notes 


Image-creation 
functions 


ImageCreate ( ), 
ImageCreateTruecolor( ), 
ImageCreateFromGd ( ), 
ImageCreateFromJpeg( ) 


These functions return a new gd image. 
ImageCreate( ) takes a width and height 
as arguments; others take a filepath, URL, or 

Qtrinp i^nntainincr ^ nrppvi^tinp imacip tn nan 

3L1 HI& 1 LCM 1 II 1 1 K 1 1 IJICC\l3Llllfci II 1 It I ^ t_ 1 1 7 (1 V 1 

in and convert to gd. 


Color allocation 


ImageCo" 
ImageCo" 
ImageCo" 


orAl 1 ocate ( ), 
orAl 1 ocateAl pha ( ), 
orDeal 1 ocate( ) 


ImageColorAllocateO takes an 
image and the desired red, green, and 
blue color values, and returns the color 
value to be used for subsequent drawing. 
ImageCol orAl 1 ocateAl pha takes an 
additional transparency value (0-127). 


Color matching 


ImageCo" 
ImageCo' 
ImageCo' 
ImageCo' 


orCl osest ( ) , 
orCl osestAl pha ( ), 
orExact( ), 
orExactAl pha ( ) 


Return the index of a matching color in a 
palette image. The "Closest" functions return 
the best-matching color by RGB distance; 
the "Exact" functions return a color only if it 
is identical, -1 otherwise. "Alpha" functions 
operate on 4-value (transparent) colors. 


Line-drawing 
functions 


ImageLi ne( ), 
ImageDashedLi ne( ), 
ImageRectangl e ( ), 
ImagePol ygon ( ), 
ImageEl 1 i pse ( ), 
ImageArc ( ) 


These functions draw lines or curves in the 
specified shapes. Usually the first argument 
is an image, the last argument is a color, 
and the intermediate arguments are x- and 
y- coordinates. 


Pen-setting 
functions for line 
drawing 


ImageSetSty 1 e ( ), 
ImageSetThi ckness ( ) 


These functions alter settings that affect 
the lines created by later line-drawing 
commands. (Some of these are available 



only with gd 2.0.1 or later.) 
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Type 


Examples 


Notes 


Painting and 
filling functions 


ImageFi11edRectangle( ), 
ImageFi 1 1 ed El 1 i pse( ), 
ImageFi lied Re ctangleO, 
ImageFi lledPolygon(), 
ImageFi 1 1 edArc( ), 
ImageFi 1 1 ( ) 


Usually analogous to corresponding line- 
drawing functions but with areas filled rather 
than outlined. The special ImageFi 1 1 ( ) 
function "flood fills" outward from a 
specified x-y-coordinate with a given fill 
color. (Some of these functions require gd 
2.0.1 or later.) 


Text functions 


ImageStri ng ( ), 
Imagel_oadFont( ) 


ImageStri ng takes as arguments an 
image, a font number, x- and y-coordinates, 
a text string, and a color. If the font number 
is between 1 and 5, one of the five built-in 
fonts is used to draw the string in the given 
color. A number greater than 5 indicates 
a result of loading a custom font with 
ImageLoadFont( ). 


Exporting 
functions 


ImagePng ( ), 
ImageJpeg ( ) 


These functions convert the internal gd 
image to the relevant image format and then 



send to output. If only one argument (an 
image) is given, the image is echoed to the 
user; if an additional path name argument is 
given, the destination is a file. 

Image- ImageDestroy ( ) Takes an image argument and frees all 

destruction resources associated with the image, 

function 



Images and HTTP 

Before the user's browser can display an image appropriately, it has to know that an image is com- 
ing, and what the image format is. So it is, unfortunately, not sufficient to simply embed a call to 
ImageToPng ( ) in your generated HTML and have an image show up. You essentially have three 
choices in regard to intermixing images with PHP-generated HTML. 

Full-page images 

You can make the entire generated page an image. In this case, you need to send an HTTP header 
before the image data, announcing that an image of a certain type is on the way. You may, for exam- 
ple, have lines such as the following near the end of your script: 

// ... code to create image in limage 

header( "Content-type : image/png"); // announcement to browser 

imagepng($image) ; // sending actual PNG-converted image data 

imagedestroy($image) ; // freeing resources 
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This approach has the benefit that you can use any kind of information, including POST arguments, 
to decide what the image should contain. The downside is that the resulting page can't contain any 
conventional HTML. In fact, you need to be careful that no textual output is sent from your scripts 
before the header and image because this causes content to be sent prematurely. In this case, you get 
a Headers al ready sent . . . error. 

Embedded images from files 

Of course, HTML has had the < I MG> tag for a long time. This enables you to embed an image by 
specifying its file path or URL, like this: 

< I MG SRC="my_png . png"> 

This works with static image files, but there is no reason why the image can't have been recently cre- 
ated. So you can have a script that (1) creates an image, (2) writes the image data to a local file, and 
then (3) produces HTML with an appropriate < I MG> tag referring to the file that you just made. 

The only drawbacks to this approach are that you're introducing file writes, which may be time- 
consuming, into the page-generation process, and that you need to figure out what to do with the 
files after you are done with them. There is one situation this approach is perfect for, however, which 
is creating and caching images that represent a finite set of possibilities. In this case, you have some 
way to map from a situation to an image filename. Whenever a display situation arises, you check 
to see if you already have the appropriate file — if you do, you simply refer to it by using an < I M G > 
tag, and if not, you create the image, write it out to a file, and then refer to it. Eventually, you should 
need to do no more creation. 

Embedded images from scripts 

Finally, there is no reason why you cannot have a standalone generated image, as in the section 
"Full-page images," but, in turn, embed that URL in a different dynamic page via an <IMG> tag. 
The only difficulty lies in how to communicate necessary data to the dependent page. You may, for 
example, have an embedded image tag like this: 

< I MG SRC="ballpage.php?ball_color=green&ball_position=5> 

where ballpage.php happened to return PNG images of colored balls in various positions in 
the image. 

There is a gotcha lurking here because both web servers and browsers sometimes pay attention to 
the suffix of the served file, and in different ways. You may need the suffix ofballpagetobe .php 
to let Apache (for example) know that the server-side code should be interpreted as PHP (although 
this behavior can be controlled with configuration files). Some broken browsers, however, may insist 
that a file that ends in .php cannot be an image despite the headers we are sending. This technique 
requires some cross-browser testing to make sure that your intended users are seeing the same thing 
you are. 

Now it's high time to move on to an example of using gd to create images. 
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Example: fractal images 

There's a fine tradition of livening up the potentially unexciting topic of line drawing by using frac- 
tals as examples, and your authors are not about to mess with tradition. In addition to showing how 
you can produce a complex image programmatically, this kind of example is also a good fit for PHP 
because its arrays and loose data types make it very easy to build complex data structures corre- 
sponding to fractal images, without a lot of declarations. 

What's a fractal? It's a shape that is self-similar, in that the parts of a fractal have a shape similar to 
the shape of the whole, and the parts of those parts have a similar shape, and so on. 

In theory, you can keep zooming into ever-smaller pieces of an ideal fractal, and keep finding the 
same patterns repeated. In practice, computer-generated fractals bottom out after some limited num- 
ber of generations into nonfractal shapes like simple curves and line segments. 

An example of the kind of image we're going to create is shown in Figure 42-3. Although it may not 
look like it, this image is simply a lot of small line segments with endpoints connected into a path. 



FIGURE 42-3 



Fractal 1 
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Our job is to calculate the endpoints of all those line segments and then display them appropriately 
as a PNG image. We're going to be slightly more ambitious than simply creating a one-off piece of 
fractal display code and construct a little framework that makes it easy to vary the fractal parameters 
and to generate new kinds of displays. 
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To start with, we build some data structures to represent the complex shapes that we are displaying. 
We use these data structures both in our intermediate calculations and for drawing the end result. 
Let's say somewhat arbitrarily that: 

■ A coordinate point is a pair of numbers. 

■ A path is a list of points. 

We end up drawing paths by drawing line segments between all the points in a path. If we want to 
draw a simple line segment, we draw a path that has two points in it; if we want to draw a rectangle, 
then we draw a path that has five points in it (with the starting point repeated to close off the rect- 
angle). (We could have made a line segment a primitive entity here, but paths seemed more concise 
for our fractal purposes.) 

Now, how shall we represent points and paths? The easiest way to make lists of things in PHP is to 
use arrays. So we declare that a point is an array that happens to contain two numbers, and a path is 
an array that happens to contain a sequence of points. The resulting structures are multidimensional 
PHP arrays, but if we define well-named constructor and accessor functions, we can forget about 
that and just write code that acts as though these things are genuine data types. 

Listing 42-4 shows the code used to create Figure 42-3. The code defines the data types in terms 
of functions to create them (starting with ma ke_), functions to access their parts, and functions to 
draw them into an image (starting with d i s p 1 ay_). Points cannot be drawn and have no display 
function; paths are drawn by drawing lines between successive pairs of points. 

The function transf orm_path takes an input path as first argument, and as second argument it 
takes the name of a function that, in turn, is expected to take a path as argument and return a path 
as a result. The third argument to transf orm_path ( ) is a number of times that the path-to-path 
function should be successively applied to create a new path. The reason that this kind of second- 
order function is useful is that, otherwise, we may find ourselves writing a new looping function 
every time we want to build a new fractal. With this approach, we can bundle the varying part of 
the fractal code into a function that we pass into t ransf orm_pa th and avoid duplicating work. 

The spike function takes a path as argument and returns a path where every two-point line segment 
has been replaced by a five -point line segment with a spike in the middle. The t o p - h a t function 
does something similar, except that six points are involved, and the spike is rectangular. We also 
include a couple of functions to create rectangular paths of standard sizes, to use as starting points. 

After loading all the functions from the included files, the remaining code creates a gd image of spe- 
cific height and width and allocates colors into that image. (The background is white, and the lines 
are black.) 

The fractal creation code starts off by creating a standard rectangular path (containing five points 
and, therefore, four [implicit] line segments). It then passes this off to the transf orm_path func- 
tion, asking it to return the path that results from applying the spi ke ( ) function to the rectangle 
four times. The rectangle path starts with four line segments, and every segment is itself replaced by 
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four segments. So the four successive iterations have 16 segments, 64 segments, 256 segments, and 
1024 segments, respectively. 

Then all that remains is to display the complicated path that we've generated. We call our own func- 
tion di spl ay_path ( ) to draw all the lines into the image, send off an HTTP header announcing a 
PNG, call i magepng ( ) for the conversion and output, and then dispense with the internal gd image. 



LISTING 42-4 



fractah.php 

<?php 

// — points 

// A point is just a pair of numerical coordinates 

function make_point ($x, $y) ( 
return ( array ( $x , $y ) ) ; 

} 

function point_x ($point) { 
return($point[0]); 

} 

function point_y ($point) { 
return($point[l]); 

) 

// — paths — 

// A path is a list of points 

function make_path () I 
return array ( ) ; 

} 

function add_poi nt_to_path ($path, $point) ( 
$path[] = $point; 
return ( $path ) ; 

) 

function display_path ($image, $path, $color) ( 
static $line_count = 0; 
$prev_point = NULL; 
foreach ($path as $point) ( 
if (Ipoint && $prev„point) ( 
$1 i ne_count++; 
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i magel i ne ( $i mage , 

poi nt_x( $prev_poi nt ) , 
poi nt_y ( $prev_poi nt ) , 
poi nt_x( $poi nt ) , 
poi nt_y ( $poi nt ) , 
$col or ) ; 

1 

$prev_point = $point; 

} 

} 

function transf orm_path ( $path_i nput , 

$f uncti on_name , 
$iterations) ( 

// Expects a path, a path-to-path function 

// and a number of times to apply the 

// function. 

// Returns a path 

$path_to_return = $path_input; 

for ($i = 0; $i < $iterations; $i++) 1 

$path_to_return = $f uncti on_name( $path_to. 

1 

return ( $path_to_return ) ; 



function spike ($path) ( 

// Takes a path and returns a path 
$path„to„return = ma ke„path ( ) ; 
$prev_point = NULL; 
foreach ($path as $point) 1 
if ($point && $prev_point) ( 
$path_to_return = 

add_poi nt_to_path ( $path_to„return , 
$prev_poi nt ) ; 

$path_to„return = 

add_poi nt_to_path ( $path_to_return , 
poi nt_a 1 ong_segment ( $prev_poi nt , 
$ p o i n t , 
0.25)); 

$path_to_return = 

add_poi nt_to_path ( $path_to_return , 
poi nt_of f_segment ( $prev_poi nt , 
$ p o i n t , 
0.5, 0.23)) ; 

$path_to_return = 

add_poi nt_to_path ( $path_to„return , 
poi nt_al ong_segment( $prev_poi nt , 
$ p o i n t , 
0.75)); 

$path_to_return = 
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add_poi nt_to_path ( $path_to_return , 
$ p o i n t ) ; 



$prev_point = $point; 

} 

return ( $path_to_return ) ; 



function top_hat ($path) ( 

// Takes a path and returns a path 
$path„to__return = ma ke_path ( ) ; 
$prev_point = NULL; 
foreach ($path as $point) ( 
if (Ipoint && $prev„point) { 
$path_to_return = 

add_poi nt_to_pa th ( $path_to_return , 
$prev_poi nt ) ; 

$path_to_return = 

add_poi nt_to_path ( $path_to_return , 
poi nt_al ong_segment( $prev_poi nt , 
$ p o i n t , 
0.35) ) ; 

$path_to_return = 

add_poi nt_to_path ( $path_to_return , 
poi nt_of f_segment ( $prev_poi nt , 
$ p o i n t , 
0.35, 0.24) ) ; 

$path_to„return = 

add_poi nt_to_path ( $path_to_return , 
poi nt_of f_segment ( $prev_poi nt , 
$ p o i n t , 
0.65, 0.24)); 

$path_to_return = 

add_poi nt_to_path ( $path_to_return , 
poi nt_al ong_segment( $prev_poi nt , 
$ p o i n t , 
0.65) ) ; 

$path_to_return = 

add_poi nt_to_pa th ( $path_to_return , 
$ p o i n t ) ; 

} 

$prev_point = $point; 

} 

return ( $path_to_return ) ; 



function poi nt_al ong_segment ( $f i rst_poi nt , 

$second_poi nt , 
$proporti on ) 
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{ 

$delta_x = ( poi nt_x( $second_poi nt ) - 

poi nt_x( $f i rst_poi nt ) ) ; 
$delta_y = ( poi nt_y ( $second_poi nt ) - 

poi nt_y ( $f i rst_poi nt ) ) ; 
return ( ma ke_poi nt ( poi nt_x ( $f i rst_poi nt ) + 
$proportion * $delta_x, 
poi nt_y ( $f i rst_poi nt ) + 
$proportion * $delta_y)); 

} 

function poi nt_of f_segment ( $f i rst_poi nt , 

$second_poi nt , 
Sproporti on , 
$proportional_di stance) 

{ 

$delta_x = ( poi nt_x( $second_poi nt ) - 

poi nt_x( $f i rst_poi nt ) ) ; 
$delta_y = ( poi nt_y ( $second_poi nt ) - 

poi nt_y ( $f i rst_poi nt ) ) ; 
return ( ma ke_poi nt ( poi nt_x ( $f i rst_poi nt ) + 
$proportion * $delta_x - 
Sproporti onal_di stance * 
$del ta_y , 

poi nt_y ( $f i rst_poi nt ) + 
$proportion * $delta_y + 
Sproporti onal„di stance * 
$del ta_x) ) ; 

} 



function make_smal l_rectangl e () ( 



$path 


= make_path( 


); 












$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 7 5 , 


275)); 


$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 3 7 5 


, 275)) 


$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 3 7 5 


, 125)) 


$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 7 5 , 


125)); 


$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 7 5 , 


275)); 


return ( $path ) ; 














ncti on 


ma ke_l a rge_ 


rectangl e ( ) ( 








$path 


= make_path( 


); 












$path 


= add„point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 5 , 


5)); 


$path 


= add„point_ 


to. 


.path 


( $path , 


ma ke_ 


_point(495 


, 5)); 


$path 


= add„point_ 


to. 


.path 


( $path , 


ma ke_ 


_point(495 


, 395)) 


$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 5 , 


395)); 


$path 


= add_point_ 


to. 


.path 


( $path , 


ma ke_ 


_p o i n t ( 5 , 


5)); 



return ( $path ) ; 
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$IMAGE_WIDTH = 500; 
$ I MAG E_„H EIGHT = 400; 

$image = imagecreate( $IMAGE_WIDTH , $ I M AG E_H E I GHT ) 

or die("Could not create image"); 
$background_col or = ImageCol orAl 1 ocate ( $ i mage , 255, 255, 255); 
$drawi ng_col or = ImageCol orAl 1 ocate( limage , 0, 0, 0); 

$path = make_smal l_rectangl e( ) ; 

$path = transf orm_path ( $path , 'spike', 4); 

di spl ay_pa th ( $i mage , $path, $drawi ng_col or ) ; 

header(" Content- type: image/png") ; 
imagepng($image) ; 
imagedestroy($image) ; 



?> 



Although we won't show it as a separate listing, we took a copy of Listing 42-4, changed the function 
name argument from spi ke to top-hat, and renamed the file fractal2.php. The resulting 
image is shown in Figure 42-4. 



FIGURE 42-4 



Fractal 2 



fractal2.ph)> |PNG Image, 500x400 pixels) Molilla (Build ID: 2002051006 
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" , ' ' - ^j" O* 1 '^''- ' Creating and displaying these images can be time-consuming and the more so the more 
line segments are created. Your web server may time out while the creation is happening. 
Your options then are to decrease the number of generations in the fractal code or to raise the timeouts 
in your web server or PHP configuration files. 

Tweaking fractal code is definitely an art, and your humble authors are not particularly good artists. 
We wish you luck in improving on our images. 



j Cj^rj^J^.j-' P_p ^ or a muc ' 1 more extended example of producing graphics with gd, see Chapter 45. 



Gotchas and Troubleshooting 

Code to produce images can be especially difficult to debug, because some of the simplest tricks (for 
example, diagnostic print statements) can't be used as easily. What follows is a list of symptoms you 
may encounter in running gd-enabled PHP code and some things you can try to correct them. 

Symptom: completely blank image 

Sometimes your code runs without incident or apparent error, but the image that results is a blank slate, 
although you expected it to be full of graphic wonders. Some things to check (some obvious, some not): 

■ Are you drawing outside the bounds of the image? (If your image is 100 100, a small 
circle drawn at (200, 200) cannot be seen.) 

■ Are you drawing infinitesimally small graphics? (A circle with a center in range of the 
image with a radius of zero or near-zero may be completely undetectable.) 

■ Are you drawing by using the background color? (White-on-white is the same as white.) 



Symptom: headers already sent 



This problem is almost always due to printing text to output before the header call that announces a 
graphic image. Just as with other HTTP headers (such as those setting cookies), you must ruthlessly 
root out any printing of text before that call, even if that text is composed of blank lines or spaces. 

One common pattern is to see something such as the following in your browser as you test: 

Warning: Division by zero in 

/usr/local/apache/htdocs/graphics/ fractal l.php on 

1 ine 18 

Warning: Cannot add header information - 

headers already sent by (output started at 
/usr/1 ocal /apache/htdocs/graphi cs /fractal 1 . php : 18) in 
/usr/1 ocal /apache/htdocs/graphi cs/f ractal 1 .php on line 19) 
PNG 

IHDR [trailing off into binary gibberish] 
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The binary gibberish is, of course, your image data, which is being printed as text in your browser, 
resulting in nonsense characters. The reason you're seeing it as text is that the image announcement 
headers could not be sent, because some text was sent before those headers were encountered. And 
that text that was sent, in turn, was probably just (in this case) the text of the division-by-zero warn- 
ing itself. Fixing the division-by-zero problem (or whatever the error or warning is in your case) may 
eliminate the printed error, which may make the header-sending statement happy, which may mean 
a successful image display. 

If, instead, the very first thing you see is the warning about headers, you may be sending blank lines 
or spaces before the header without being aware of it. Look for any print statements, any included 
HTML, and (especially) any space at the beginning or end of files that have been included or 
required. If an included PHP file so much as ends with '? > ' rather than '? >', you may be sending a 
space's worth of HTML, which would cause text headers to be sent before the image headers are seen. 

Symptom: broken image 

How exactly this problem displays depends on your browser program — some display a sad, visibly 
broken image icon, while Firefox may politely inform you that your image can't be displayed because 
it contains errors. Either way, though, the problem is that your browser cannot read the data in the 
image format you said you were sending. Some possible causes are: 

■ The flip side of the previous Headers already sent problem: You may be printing 
random text without being aware of it but, in this case, after the image header has already 
been sent rather than before. This text is interfering with the stream of image data. 

■ You have misspelled the variable containing your image — for example imagepng($imag) 
where you meant imagepng($ image). You are actually calling the convert-and-send func- 
tion on nothing at all. 

■ Your convert-and-send function is actually producing a text error rather than a graphic 
image (possibly because you don't actually have support for that image type compiled 
into PHP). 

■ You have actually somehow screwed up your internal gd image well before trying to send it 
off. One very common cause of this is failure to allocate colors in a palette-based image or 
to use color indexes that haven't been allocated. 

In our experience, the best way to debug these sorts of problem is simply to comment out the PHP 
statement that sends the header announcing an image, and then look at the output as text in your 
browser. If everything were working perfectly, you would expect to see your binary image data as 
text, which would mean a lot of strange-character gibberish, possibly starting with a short amount 
of recognizable text (like PNG). If you see a PHP warning or error instead of the image data or in 
addition to the image data, you can proceed to debug that. If you see nearly nothing, not much of an 
image is being sent — this may imply problem #2 or #4 above. If you see what looks like a reason- 
able amount of pure image data, you may need to look at your code very carefully for small amounts 
of text (like spaces) that you may have introduced. 



711 



Part V 



Connections 



Summary 



If you create on-the-fly graphic images by using PHP, you're creating something completely different 
from the usual HTML that PHP generates — a completely different format, and a completely differ- 
ent look. Although there are hassles associated with getting the gd image library working, after you 
get past those you have quite a rich set of image-manipulation functions to work with. You can cre- 
ate web pages that are all image, or pages that have < I MG> tags that link to dynamic images, or you 
can start building a library of image files for display later on. Either way you go, you have a richer 
vocabulary to work with than with pure HTML, and (even if many situations don't require dynamic 
images) you have another type of tool in your kit. 
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Developing a Weblog 
with PHP 



Small standalone PHP applications, such as polls and e-mail forms, 
are all very useful, but complete content sites are where PHP really 
shines. Here we give complete instructions for developing the sim- 
plest type of standalone site, which is the weblog. 



WhyWeblogs? 



A weblog is the simplest kind of dynamic site. It can be thought of as a 
dynamic version of the personal home page: a content site organized by 
chronology with frequently updated posts. Most weblogs do not create all 
their own content in the sense of writing full news stories or producing 
a trove of artwork; they instead exist to comment on other people's con- 
tent and events of the day or to provide a venue for personal thoughts and 
reflections. On the high end of the genre, public weblogs like Slashdot can 
become extremely popular meeting places for online communities to chew 
the fat of their common interests. 



IN THIS CHAPTER 



Why weblogs? 
Building a simple weblog 
Adding an HTML editing tool 
Changes and additions 



If you are a newcomer to server-side scripting, we encourage you to imme- 
diately start a personal weblog as your first major project. Nothing helps 
you learn faster than running an actual complete site of your own, where 
you can try out a range of new techniques and ideas in context. Especially 
because PHP and other open source technologies grow and change so 
quickly, it's well-nigh essential to have a preexisting testbed always avail- 
able to doodle around on. 

Weblogs are also just fun and therefore, worthwhile even for those who 
also use PHP in more serious contexts. There's no pleasure quite like 
that of conducting an intellectual debate, an argument, or a romance by 
weblog. Forget movies, pop music, and reality TV — the weblog is the true 
medium of the age, baby! 
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The Simplest Weblog 

The main goal of this section is to introduce you to the layout and display aspects of building a 
dynamically generated site. In later sections, we will refine our techniques for handling the data- 
related aspects. At the end of this chapter, you should have the ability to make and maintain a sim- 
ple data-driven site of your own. Conceptually, even the most complicated dynamic content sites are 
basically just bigger versions of the concepts you will learn by building a personal weblog. 

The easiest weblog is just a PHP template and some included text files. It's limited to local develop- 
ment only — in other words, you won't be able to make entries via HTTP but only by creating text 
files while logged in to the PHP server as a trusted user (or copying text files to the server via some 
mechanism like scp (secure copy), which amounts to the same thing). You also won't be able to 
assign different levels of permissions very effectively, so this style of weblog is most appropriate for a 
purely personal single-author site. 

We decided to use the most basic type of navigation, Previous and Next text links that we'll main- 
tain by hand. This gives you the maximum flexibility to decide how often you want to change the 
front page of your weblog — we'll do it daily, but you may prefer a weekly, monthly, or irregular 
changeover, depending on how much you have to write about. We'll also include an old reliable left- 
side navbar with links to standalone pages, such as About Me and Favorite Things information. A 
finished weblog page is shown in Figure 43-1. 



FIGURE 43-1 



A weblog page 



3PHP4 Bible simple weblog: 20070504 -Miciosofl Internet Exploier 
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Today 
Links 
Faves 
About me 
Contact 



*s] Done 



<— Previous 
RECIPE 



Weblog entry for 20020504 



Next 



Strawberry shortcake is the greatest of American desserts. 
The month of May is the time in most areas. 

Wash, dry, and hull: 

• 1 pint strawberries (preferably Sparkle) 
Macerate for at least 1 hour with: 

■ 4 Tablespoons sugar 

• 2 Tablespoons Grand Marnier 

Meanwhile, make shortcakes. Dump Into a bowf: 

•£ Internet 
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It is assembled from these files: 

weblog. php: Main display page template 

20040101.txt, 20040102.txt: Weblog entries (changed daily) 

default.txt: Default text entry for days when there is no new content 

f avori tes . php, 1 i n ks . php, aboutme . php: Semistatic pages (changed infrequently) 

header. inc: Header and navigation bar on every page 

footer .inc: Footer on every page 

s ty 1 e . i n c : Internal style sheet 

You must change the variable $ i ni t i al _ent ry_date in webl og . php to the date of 
your first entry, or you may start an infinite loop that will eat up all your server cycles! 
You must also check all the paths to included files and change them to real paths. 



CAUTION 



Listings 43-1 through 43-7 are the code for a simple weblog. Instead of using a database to store 
your entries, the data will be stored in text files on your filesystem. 



LISTING 43-1 



Main weblog template (weblog.php) 

<?php 

// 

// GET YOUR VARIABLES ALL LINED UP 

// 

// Change this to the date of your first log entry. 
$initial_entry_date = 20040101; 

// Replace the fake path below with a real one 
$D0CUMENT_R00T = "c: \docs" ; 

$today = date( ' Ymd ' ) ; 

if (isSet($_GET['date'])) { 

if ($_GET[ 'date' ] < $i ni ti al_entry_date ) ( 

// Go to first entry if the specified date is earlier 

// than range 

$date = $i ni ti al_entry„date ; 
I elseif ($_GET[ 'date' ] > Itoday) { 

// Go to last entry if specified date is later than range 

$date = $today; 
( else ( 

$date = $_GET[ 'date' ] ; 

} 

) else j 

$date = $today; 

} 
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$title_msg = $date; 

$header_msg = "Weblog entry for $date"; 

// Assemble the Previous/Next links 
$prevdate = $date - 1; 
$nextdate = $date + 1; 
if ($date == $ i ni t i a 1 _ent ry_date ) ( 
$flipbar = "\n<P CLASS=\"next\"> 
<A HREF=\"weblog.php?date={$nextdate}\">Next --></A> 
</P>\n" ; 

1 elseif ($date == $today) ( 

$flipbar = "\n<P CLASS=\ " previ ous \ " > 
<A HREF=\"weblog.php?date=($prevdate}\"><-- Previ ous</A> 
</P>\n" ; 
( else { 

$flipbar = " \n<TABLE B0RDER=0XTR> 
<TD WIDTH=\"50%\" ALI GN=\ " 1 ef t \ " > 
<SPAN CLASS=\"previous\"> 

<A HREF=\"weblog.php?date=($prevdate}\"><-- Previous</A> 
</SPAN> 

</TDXTD WIDTH=\"50%\" ALIGN = \"right\"> 
<SPAN CLASS=\"next\"> 

<A HREF=\"weblog.php?date=($nextdate}\">Next --></A> 

</SPAN> 

</TD> 

</TRX/TAB LE>\n " ; 

} 



// 

// NOW ASSEMBLE THE PAGE 

// 

incl ude_once( 'header. inc' ) ; 

echo $flipbar; 

// Include the specified text file, or a default message 

// Replace the fake path below with a real one 

if (file_exists($DOCUMENT_ROOT. "/path/to/entri es/$date . txt" ) ) { 
// Replace the fake path below with a real one 
incl ude($D0CUMENT_R00T. "/path/ to/entries /$date. txt" ) ; 

( else { 

i ncl ude ( " default. txt"); 

} 

echo $flipbar; 

incl ude_once( 'footer. inc' ) ; 

?> 
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LISTING 43-2 



A dated entry (20000101.txt) 

<DIV CLASS="topic">HOLIDAY</DIV> 

<P>0h, what a holiday season it has been! I am positively 
stuffed with fruitcake. </P> 



<P>My New Year's Resolutions are: 
<UL> 

<LI>Trade in AMC Greml i n . </LI> 

<LI>Contri bute to OSS pro j ect . </ LI > 

<LI>Take full 2 weeks vacation (dude ranch? ).</ LI > 

<LI>Be less snide. </LI> 

</UL> 

</P> 



LISTING 43-3 



Default message (default.txt) 

<P>Sorry, nothing new today! Check back tomor row . </ P> 



LISTING 43-4 



A static page (favorites. php) 

<?php 

$title_msg = 'favorites'; 
$header„msg = 'My favorite things'; 

include_once( 'header. i n c ' ) 

?> 

<P>These are a few of my favorite things. </P> 

<DIV CLASS="topi c">B00KS</DIV> 
<DL> 

<DT>Cryptonomi con , by Neal Stephenson</DT> 

<DD>The techie masterpi ece- - i t ' s our life, put in the blender 
of a massive inventiveness. Be sure to also download the essay 
"In the beginning was the command line" from his site, 
www.crytonomicon.com .</DD> 
</DL> 
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<DIV CLASS="topic">MUSIC</DIV> 
<DL> 

<DT>Raw Power, by The Stooges</DT> 

<DD>See who all those neo-punk bands are copying. </DD> 
</DL> 

<?php i ncl ude_once( ' footer . i nc ') ; ?> 



LISTING 43-5 



Included header file (header.inc) 

<HTML> 
<HEAD> 

<TITLE>PHP4 Bible simple weblog: 
<?php echo $_GET['date']; ?></TITLE> 
<?php include("style.inc"); ?> 
</HEAD> 

<B0DY BGC0L0R="#FFFFFF"> 

<TABLE B0RDER="0" C E L L PADD I N G= " 5 " W I DTH = " 1 00% " > 
<!-- Title box --> 

<TR WIDTH="100%" BGC0L0R="#822222"> 

<TD WIDTH="100%" ALIGN="right" C0LSPAN="2"> 

<HlX?php echo $header_msg; ?></Hl> 
</TD> 

</TR> 

<!-- End Title box --> 



<!-- Begin main body --> 
<TR WIDTH="100%"> 

<TD WIDTH="20%" VALIGN="top" BGC0L0R="#FFFECC"> 
<!-- Navbar --> 

><A 
><A 
><A 
><A 
><A 



<P 
<P 
<P 
<P 
<P 



CLASS= 
CLASS= 
CLASS= 
CLASS= 
CLASS= 

HREF="mai 1 to:me@l oca 1 host 
<!-- End Navbar --> 
</TD> 

<TD WIDTH="80%"> 



'sidebar' 
'sidebar' 
'sidebar' 
'sidebar' 
'sidebar' 



HREF="webl og . php">Today</AX/P> 
HREF=" links. php">Links</AX/P> 
HREF=" favorites . php">Faves</AX/P> 
HREF="aboutme.php">About me</AX/P> 



>Contact</AX/P> 
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LISTING 43-6 



Included footer (footer.inc) 

<!-- End of main body --> 

</TDX/TR> 

</TABLE> 

<P CLASS="footer">Copyright Wiley, Inc. 2000 - 2009</P> 

</B0DY> 

</HTML> 



LISTING 43-7 



Included stylesheet (style. inc) 

<STYLE TYPE="text/css"> 

<!-- 

BODY, P, LI {font-family: verdana, arial, sans-serif; 
font-size: 12pt; color: #000000; text-align: left; 
margi n-1 eft : lOpx) 

HI {font-family: verdana, arial, sans-serif; 

font-size: 14pt; color: #FFFFFF] 

A:link, A:visited {font-family: verdana, arial, sans-serif; 
font-size: 12pt; color: #822222; text-decorati on : none ) 
.sidebar { font- f ami 1 y : verdana, arial, sans-serif; 
font-size: 12pt; color: #822222; text-al i gn : ri ght ; 
ma rgi n - top : 10 ; ma rgi n- ri ght : 7 ) 

.topic { font- f ami 1 y : verdana, arial, sans-serif; 

font-size: 12pt; font-weight: bold; color: #000000; 

background: #FFFECC; text-align: left) 

.footer (font-family: verdana, arial, sans-serif; 

font-size: 9pt; color: #808080; text-al i gn : ri ght ) 

.previous {font-family: verdana, arial, sans-serif; 

font-size: 12pt; color: #808080; text-align : 1 eft ; 

margi n - 1 ef t : 25 ; margi n-right:100) 

.next {font-family: verdana, arial, sans-serif; 

font-size: 12pt; color: #808080; text-al i gn : ri ght ; 

margi n-left:100; margi n-right:25) 

--> 

</STYLE> 



To use the simple weblog, place all the files in a PHP-enabled directory on your web server. Create a 
subdirectory for your daily entries (for example, 20000101.txt, 20020504.txt); otherwise, you'll 
quickly end up with dozens of files cluttering up your main directory. The files in this subdirectory 
need to be writable by you and readable by all. 
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When you're ready to make an entry, log in to your web server, fire up a text editor such as v i , 
and write an HTML-formatted text file for each day you want to post, naming it according to the 
date convention we've established. Alternatively, instead of logging in to your web server, you can 
write up your daily text file on a local client copy and then use s cp to upload it to your web server. 
Obviously, you can edit this file however many times you like, if you have multiple things to say per 
day. As long as the files have the correct names, locations, and permissions, this code should run 
smoothly for you. This type of weblog is self-archiving, so you don't need to do anything special 
with old entries — they'll just stay around forever if you have a big enough hard disk. 

"FT? r ' ! 'f y° u s *'" use FTP *° upload f'les, please take an hour to learn how to use scp instead. 

A fine command-line Windows client called pscp is available for free downloading at 
www .chiark.greenend.org.uk/~sgtatham/putty.An even easier GUI Windows client called 
Wi nSCP is available for free downloading at http://winscp.sourceforge.net/eng. FTP should be 
used only for file downloading, for example from anonymous FTP servers, because it has caused so many 
security problems when uploading files. One of the reasons to avoid the otherwise fine weblog-publishing 
applications such as Movable Type and Blogger is that they rely on FTP to write files to your web server. 

We promise that scp is just as easy to use, if not easier — instead of typing ftp my server, my domain 
. com and put myf i 1 e . php, you combine both commands into the simple pscp myf i 1 e . php me@ 

my server . mydoma i n . com : myf i 1 e . php. 

If you really can't make up your mind to learn scp, it might be safer to use an HTTP-based editing tool 
as detailed in the next section. 



Adding an HTML-Editing Tool 

This simple weblog is quite adequate for many purposes, but it has one big disadvantage: You can't 
write up your daily entries using the web itself. Instead, you must create each entry using a text edi- 
tor such as emacs or Notepad and save it to your web server's docroot. This can be a significant 
issue over time, especially if you are not allowed ssh/FTP access to your server or aren't comfortable 
with the process. HTTP is the next logical step for many users, and it is probably no less unsafe than 
using FTP. 

This process has one big problem: You need to give read/write permissions to the HTTP user (usu- 
ally Nobody) in a particular directory. This is an inherently insecure process, and we do not recom- 
mend it in the long run. We'll describe the HTTP tools here so that you can become comfortable 
with the new aspects before moving on to a better solution, which is using a database instead of 
separate i ncl ude ( ) files for each entry. We'll also try to keep the security problems to a minimum, 
employing a password and letting you send mail to yourself if an unauthorized person tries to log in. 

The files you need for an HTML-based file-writing tool are: 

■ 1 o g i n . p h p 

■ logentry.php 

■ 1 ogentry_handl er . php 

■ password. inc 
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Put password, inc in a directory outside the web tree, such as / home / html user. This will ensure 
that your passwords cannot be read via the web without being processed by PHP first. The directory 
must be world-executable and the document must be readable by the httpd user (Nobody). If you 
have root access on this server, you could chown it to belong to the httpd user; if not, you may have 
to make the file world-readable, which is a security breach. Be sure to use a password different from 
your system user password, just in case it's compromised. 

Listings 43-8 through 43-10 are the files you need for an HTML form to edit weblog entries. 



LISTING 43-8 



Weblog entry login screen (login. php) 

<HTML> 
<HEAD> 

<TITLE>Webl og login screen</TITLE> 
</HEAD> 

<PXB>Supply a username and password . </BX/P> 
<F0RM METH0D=P0ST ACTI0N=" 1 ogent ry . php "> 
<P>USERNAME: 

<I NPUT TYPE=TEXT NAME="test_username" SIZE=20X/P> 
<P>PASSW0RD: 

<I NPUT TYPE=PASSWORD NAME="test_password" SIZE=20X/P> 
<P>BL0G ENTRY : <BR> 

<TEXTAREA N A M E = " 1 ogtext" C0LS=75 R0WS=20WRAP="VIRTUAL"> 
</TEXTAREAX/P> 

<PXINPUT TYPE="SUBMIT" VALUE="SUBMIT"> 

</F0RM> 

</B0DY> 

</HTML> 



LISTING 43-9 



Included password file (password. inc) 

<?php 

$username = "logwriter"; 
$password = "1 ogpass" ; 
?> 
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LISTING 43-10 



Weblog data entry script (logentry.php) 

<?php 

$date = date( "Ymd" ) ; 

include("/home/htmluser/password.inc"); 

i f ( $_P0ST[ ' test_username ' ] == $username && 
$_P0ST[ ' test_password ' ] == $password) { 
$fp = f open ( " /ent ri es / $date . txt " , "w"); 
$try_entry = fwritedfp, $_P0ST[ ' 1 ogtext ' ] ) ; 
if ($try_entry > -1) { 

pri nt( "Webl og entry for $date written to disk."); 
) elseif ($try_entry == -1) { 

pri nt( "Webl og entry write failed."); 

1 

} else { 

mai 1 ( "me@l ocal host" , "Weblog snoop alert", "Someone from 
$REMOTE_ADDR is trying to get into your weblog entry 
handler."); 

} 

?> 



Changes and Additions 

Things you might want to immediately change, add, or alter in this codebase include: 

■ Alter colors, styles, layout. 

■ Allow database connectivity. 

■ Change frequency of expected updating (weekly, monthly). 

■ Change to calendar-based navigation rather than Next/Previous links. 

■ Change to topic-based rather than date-based navigation. 

■ Stop automatic entry changeover by date. 

■ Allow future entries in database. 

■ Allow multiple authors/editors with different permissions. 



724 



Developing a Weblog with PHP 



Besides a personal weblog, you could use this code for any simple, chronological note taking, such as: 

■ A vacation j ournal 

■ A project log 

■ The story of your vast weight loss through heroic diet and exercise 

■ A chronicle of your pregnancy and your baby's development 



Summary 

Although it's handy for small, standalone projects such as polls, PHP's most impressive use is in 
developing complete data-driven content sites. The easiest such site to develop is the personal 
weblog. We encourage every PHP user to keep one, if only as a handy testbed for new ideas and 
techniques. 

If you wish, you can store your data in ordinary text files, using PHP to plug these files into a 
template based on a criterion such as date. This will save a certain amount of formatting-related 
repetition at the cost of somewhat decreased security. Far better in every way is to keep the data 
in a database. 

The weblog format is very flexible. It can scale up to a major public site like Slashdot, with tens of 
thousands of contributors and a steady stream of new content upon which to comment. Or you can 
keep a little secret diary on your own laptop, reading it in a browser window on the sly. The impor- 
tant point is that once you've made a complete data-driven site with PHP, you'll never go back to 
static web pages. 
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In this chapter, we present a full working example of a small PHP appli- 
cation: a web-based trivia game with a twist (the "Certainty Quiz"). 
The main virtue of the chapter is its completeness: Instead of using 
code fragments to illustrate talking points, as we do in most other chapters, 
we're showing everything, soup to nuts. As a result, this is one of the larger 
examples in the book, weighing in at more than 1300 lines of PHP code. 



Concepts Used in This Chapter 

The code in this chapter uses a wide variety of techniques, tricks, and tech- 
nologies that we've presented elsewhere in the book. In particular: 

■ We make heavy use of the object-oriented features of PHP 
(Chapter 20). 

■ We rely on PHP's session mechanism to propagate game data from 
page to page (Chapter 24). 

■ We use a back end database (MySQL) to store questions and high 
scores (Part II). 

■ We do some behind-the-scenes mathematics, including approxi- 
mating nth roots (Chapters 9 and 27). 

■ We use arrays for storing data and for manipulating data returned 
from the database (Chapters 8 and 21). 

■ We do a lot of string processing and concatenation to build our 
display pages, including the heredoc technique for templating 
pages (Chapters 7 and 21). 

■ We use the new exception-handling features of PHP5 to catch 
database and session problems (Chapter 31). 



IN THIS CHAPTER 



A guessing game with 
approximate answers 

The object-oriented 
implementation of the game 

Database and session support 

Design considerations 
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We highlight some of these topics in various sections later in the chapter as we delve into the code. 

The Game 

Several years ago, a friend asked one of us to try a quiz he'd seen somewhere on the Internet. After I 
agreed, he told me that he would ask me 10 questions, each of which had a numerical answer (dates, 
weights, lengths, counts, and so on). The unusual part was that instead of answering with a number, 
I was to give a lower bound and an upper bound on the answer. I could make the ranges as large as I 
wanted, and otherwise I had only one instruction: Make sure that you answer nine out of ten ques- 
tions correctly. 

I answered the questions confidently and was surprised at the end to find that my final score was 
six (or was it four?). At any rate, I did surprisingly badly, but my friend said that everyone else he 
had tried it on had done even worse. Now, how could anyone lose such an easily winnable game? 
After all, when asked when Shakespeare was born, I could have said "Sometime between 30,000 
B.C. and A.D. 30,000" and been pretty sure that I would be right. What trips people up seems to be 
some combination of pride and overconfidence. The pride prevents you from giving a ridiculously 
large range (because then your questioner knows you don't have the foggiest idea when Shakespeare 
was born); the overconfidence makes you willing to narrow the range beyond your real range of cer- 
tainty. In the end, the game isn't testing your knowledge — it's testing your knowledge of your own 
knowledge (or lack of knowledge). 

Our version 

In this chapter, we implement something like this quiz game, but with some changes to make it 
more web-friendly. For one thing, rather than having the player type in numbers freely, we present 
a range of choices that the player narrows down further. For another, we don't rely on pride to make 
the ranges narrow (because people may end up playing this over the web in the privacy of their own 
home). Instead we add incentives to the scoring system to make people guess narrowly rather than 
broadly. Finally, we add some features familiar from online games, such as levels of difficulty and a 
list of top scorers. 

The upshot is a game that, while it may or may not be fun, is certainly frustrating, which for many 
people is nearly as good. 



Sample screens 



Figure 44-1 shows the game screen as it may look to a new arrival. There is a welcome message to 
the right, and a question to the left, with radio buttons for choosing a range of answers. 
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FIGURE 44-1 



Start screen 
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Welcome to the Certainty Quiz! 

The game that tests 

* how much you know about how much and 

* how much you know about how much you know about how much! 
The object 

The goaf is to answer as many questions correctly as possible. Answer 
questions (starting with the first one at the left), by choosing values above 
and below where you think the right answer lies. Answers are correct if 
they include the real answer in (he range. The narrower your guesses, the 
longer you'll survive There are ten levels, if you think the questions are 
too easy, keep going 
Rules and scoring 

* Four points subtracted from your credit for every incorrect answer. 

| 1 |« tm«m«i 



Figure 44-2 shows the screen immediately after the player has answered the first question. Another 
question is offered on the left, and now the state of the game score is highlighted on the right, show- 
ing the correct answers to date, the credit remaining, and the level attained. (See the next section for 
an explanation of what these things mean.) 

Finally, Figure 44-3 shows "Game Over," complete with taunting message and a list of high scorers. 
(There's a corresponding "Game Won" screen in the unlikely event that the user survived all the 
questions the game could come up with.) 

The rules 

The basic play cycle is simple: The player is asked a question that requires a numerical answer, and 
the player responds by choosing a range of values that should include the answer. The goal is to 
answer as many questions correctly as possible, while surviving in the meantime. Survival depends 
on credit, which is accumulated by answering questions correctly within a narrow range and is 
spent by giving wrong answers or answering questions too broadly. 
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FIGURE 44-2 



Continuing play 
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FIGURE 44-3 



Game over 
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The exact rewards and penalties are easily tweakable in the code, but in this chapter's version they are: 

■ Correct answers: One point added to credit, minus a penalty for the size of the range 
specified. The penalty ranges from zero for answers that use only one step of the possible 
range, up to four points for making the range as wide as possible. 

■ Incorrect answers: Four points deducted from credit. 

Credit starts at five points and can rise only as high as fifteen points. The game is over when credit 
goes below zero. 

It is easy to pass by simply submitting your answer without making a choice, since the radio buttons 
are set to specify the widest possible answer range unless the player changes them. The penalties are 
set up so that passing is costly (a total of 1 - 4 = -3 points), but not as costly as guessing wrong (-4 
points). The player is better off narrowing the range as much as possible, while still being sure that 
the real answer is still included. 

Playing the game yourself 

If you just can't wait to play, we have a playable version of the game available at www . b r a i n g i a . 
org/books/pmb/trivia. 



The Code 

The code for this example is almost completely written in an object-oriented style (see Chapter 20 for 
an introduction to PHP's version of object-oriented programming). Among the classes we define are: 

■ Questi on: Each Questi on object includes the text of the question, the correct answer, the 
lower and upper bounds that are presented to the player, and enough information to dis- 
play the range of choices that the player can choose from. In addition, Questi on instances 
track whether or not they are answered correctly. 

■ Game: There should be one and only one Game object in existence at a particular time. 
Game objects may include up to two question objects (the current question and the previ- 
ous one), as well as a GamePa rameter instance. 

■ Game Para meters: Contains all the numerical settings that affect how the game behaves 
and manages some globally available resources such as the database connection. 

■ GameDi spl ay: Contains a Game instance as a component and does all the work of actually 
displaying HTML and receiving input. Also contains an instance of GameText. 

■ GameText: A repository for boilerplate HTML that is not dependent on any knowledge of 
the state of the game. Only this class and GameDi spl ay actually have HTML code in them. 
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Code files 

The code files include definitions for all the classes in the preceding section: quest i on_cl ass . 
php, game_cl ass . php, game„pa rameters_cl ass . php, game_di spl ay_cl ass . php, and game_ 
text_cl ass . php. In addition, there are some code files that don't define classes: 

■ index. php: The first file loaded, which handles sessions and post arguments and creates 
the GameDi spl ay object. 

■ c e r t a i n ty _u t i 1 s . p h p : A grab bag of initialization statements (seeding the random- 
number generator, for example) and math utility functions. 

■ entry_f orm . php: A form for adding new questions to the database. 

■ dbva rs .php: The usual file with definitions for username, password, and host for the 
database connection. 

We now take a tour of the code file listings. Rather than building from the ground up as we sometimes 
do, in this chapter we work from the top down: first the very first page that is actually loaded, then 
the code that page depends on, and so on until we bottom out in utility functions and database calls. 
Finally, at the end of the chapter, we show how to construct the database and populate it with questions. 

index. php 

Listing 44-1 shows i ndex .php, which is the user's entry point. The primary job of this file is to deter- 
mine where we are in the cycle of play, set up the appropriate PHP objects (either by creating them or 
by retrieving them from the user's session), and echo out the display code that the objects generate. 

Where we are in the course of a game is determined by a combination of session and POST informa- 
tion; as users arrive for the first time, they find neither a current session nor any POST arguments. 
Successive pages, however, should have both an active session and useful information submitted 
from the previous page. 



LISTING 44-1 



index.php 

<?php 

// Include code files, start up session 
i ncl ude_once( "certai nty_uti 1 s . php" ) ; 
i ncl ude_once( "game_di spl ay_cl ass . php" ) ; 
sessi on_start( ) ; 

// Determine state and handle post arguments 
try ( 

// CASE 1: Player is submitting name for high score list 
if ( get_sess i on„va 1 ue ( ' game ' ) && 
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get_post_val ue( ' H I GHSCORE ' ) ) ( 
if ( get_sess i on_va 1 ue ( ' game ' ) && 
get_post_val u e ( ' HIGHSCORE ' ) ) ( 
$game_di spl ay = 

new GameDisplay( get_sess i on_val ue ( ' game ' ) ) ; 

$game_di splay->handleHighScore( ) ; 

) 

} 

// CASE 2: Player is in middle of game that we are tracking 
elseif ( get_sessi on_val ue ( ' game ' ) && 
! get_post_val ue( ' NEW ) ) { 
Slower = get_post_val ue( ' 1 ower ' ) ; 
Supper = get_post_val ue( ' upper ') ; 
$game_di spl ay = 

new GameDisplay( get_sessi on_val ue ( ' game ' ) ) ; 
$game_di splay->updateWithAnswer($l ower , Supper ) ; 

} 

// CASE 3: Player has either just arrived or has 
// finished a game and asked for a new one. 
elseif ( !get_post„val ue( ' POSTCHECK' ) || 
get_post_val ue( ' NEW ' ) ) { 
$game_di spl ay = new GameDi spl ay ( new GameO); 

} 

// CASE 4: Something is wrong. 

// The page is the result of a POST operation, 

// yet we don't seem to have a live session, so 

// we are not successfully tracking a game. 

// The only thing to do is complain, and ask about 

// cookies. 

else { 

$game_di spl ay = 

new GameDi spl ay(new GameO); 

throw (new Excepti on ( "We couldn't track your game." . 
"You may have to enable cookies to play")); 

} 

// Construct string that will be displayed as page 
$page_string = $game_di spl ay->di spl ay ( ) ; 
// Store game state in session so that next 
// page can pick it up 
set_sessi on_val ue( ' game ' , 
$game_di spl ay- >_game ) ; 

) // end of try block 

catch (Exception $exception) { 

// There is a problem somewhere. Create 
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// an error page. 

$excepti on_msg = $excepti on->getMessage( ) ; 
$display = new GameDi spl ay ( nul 1 ) ; 
$page_string = 

$display->makeErrorPage($excepti on_msg ) ; 
// hope to start fresh next time 
unset_sessi on_val ue( ' game ' ) ; 



// Actually echo page to browser 
echo( $page_stri ng ) ; 



The object types that i ndex . php cares about are GameDi splay and Game. The Game object con- 
tains all the state information that needs to be preserved from page to page about where the user is 
in the game (score, questions asked already, and so on). The GameDi spl ay object contains a Game 
instance and does everything necessary to produce an HTML page from it. 

If the user is starting off for the first time, we create a new Game object, relying on the object's 
constructor to initialize it appropriately. For subsequent pages, though we rely on the automatic 
object serialization feature of PHP sessions to store the Game object for us. (The actual definitions of 
get_sess i on_val ue ( ) and set_sess i on^val ue ( ) are in certa i nty_uti 1 s . php, but all that 
is happening is that we stash the Game object in a session. PHP takes care of the serialization that is 
necessary to read the object into a session and back out again.) 

i pj-j fjCC J"j pjf For more on what it means to serialize an object, see Chapter 20; for an explanation of 
■ ~~" sessions and their workings, see Chapter 24. 

If the user is in the middle of a game, we expect both a Game object stored in the session and a form 
submission representing either a guess at the answer or a request to be listed on the High Scores page. 

Regardless of whether we create a new Game object or retrieve the one from the last page, we create 
a new GameDi spl ay object around it and then ask that object for a string that represents the entire 
HTML page. We store this in a string, ready to echo it out to the browser in the very last code line. 

Exceptions 

Many things can go wrong with the execution of this game's code. For one thing, of course, there's 
always a possibility of a code bug that leaves the game in a strange state. In addition, though, the 
code relies on at least three external "services," any of which might misbehave: 

■ The database, which stores the questions and answers 

■ The session mechanism, which is in turn probably relying on files on the hard disk 

■ Cookies stored on the user's browser, which may refuse them 
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If any of these services turn out to be unreliable, the game will not be playable. Our goal in this situ- 
ation should be to fail as gracefully as possible. 

In a previous edition of this chapter, the code had to catch all the possible failures and propagate an 
error up to this page, which would then detect the failure and display an appropriate error string. 
This time, though, we can use PHP's exception mechanism, which makes it much easier to struc- 
ture the code. Whenever we encounter a problem that cannot be recovered from, we throw the 
problem, along with a descriptive string. The catch statement in i ndex . php is the only one in the 
game's code, and so will receive any of the exceptions that happen as a result of its calls to functions 
in other code files. In addition, it will catch the exception thrown in Case 4 of i ndex . php, which 
probably indicates that the user's browser is not accepting cookies. 

i r . r r- ~'~"tj rV See Chapter 31 for an introduction to exceptions and error handling. 

game_display_class.php 

Almost all of the look-and-feel action for this game is in game_di spl ay_cl ass . php, as shown in 
Listing 44-2. 

The code file depends on two other files: game_cl ass . php and game_text_cl ass . php. The for- 
mer contains most of the logic for the inner workings of the game, whereas the latter just contains 
some boilerplate text. The job of the GameDispl ay class is to extract all the information from the 
game state necessary to produce actual HTML pages. 

The important public functions in the class are: 

■ The constructor function 

■ updateWithAnswerO, which is called with data from the user's submission of a guess 

■ makeErrorPaget), which returns HTML to display if something has gone wrong 

■ di spl ay ( ) , which returns HTML to display when everything has gone right 



LISTING 44-2 



game_display_class.php 

<?php 

i ncl ude_once( "game_cl ass . php" ) ; 
i ncl ude_once( " game_text_cl ass . php" ) ; 

class GameDi spl ay 

( 

// presentation 
public $_pageTitle 
public $_blueColor 
public $_redColor 

// contents 
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= "The Certainty Quiz"; 
= "#AAAAFF" ; 
= "#FFAAAA" ; 
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publ i c $_game = NULL; 

publ i c $_gameText ; 

public $_hi ghScorePosted = FALSE; 

// CONSTRUCTOR 

function construct ($game) ( 

$thi s->_game = $game; 

$thi s - >_gameText = new GameText(); 

} 

// PUBLIC FUNCTIONS 
// accessors 
function getPageTi tl e( ) ( 
return ($thi s ->_pageTi tie); 

} 

function getBl ueCol or ( ) { 
return ( $thi s ->_bl ueCol or ) ; 

} 

function getRedCol or( ) ( 
return($thi s->_redCol or) ; 

1 

function getGameO { 
return ($thi s ->_game ) ; 

} 

function getHi ghScorePosted( ) { 
return ($thi s ->_hi ghScorePosted) ; 

1 

function updateWi thAnswer (Slower, lupper) ( 
$game = $thi s->getGame( ) ; 
$game->updateWithAnswer($lower, Supper) ; 

} 

function makeErrorPage ( Iprobl em_stri ng ) { 
// constructs the HTML page to display when 
/// something has gone horribly wrong 
$top_matter_stri ng = 

$thi s->_makeTopMatter( $ t hi s->_pageTi tie); 
$page_string = <<<E0T 

$top_matter_stri ng 

</H2X/CENTER> 

<TABLE B0RDER=2> 

<TR> 

<CENTER> 

<H2>We're sorry, but the game is not available 
right now . </H2XH4>( $probl em_stri ng )</H4> 
</CENTER> 
</TRX/TABLE> 
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</BODYX/HTML> 
EOT; 

return($page_string) ; 

} 

f uncti on display ( ) 1 

// returns entire page as string — 

// backbone structure of page, plus 

// overridable methods to print components 

// sanity checks 



if ( ! $thi s ->„game | 

! i s_ob j ect ( $thi s ->_game ) ) { 
throw new 

Excepti on (" Cannot find valid game object"); 



elseif ( ! $thi s ->_game->getDbConnect i on ( ) ) ( 
throw new 

Excepti on (" No database connection"); 



// display of apparently valid page 
else ( 

$top_matter_stri ng = 

$thi s ->_ma keTopMatter($this- >_pageTi tl e ) ; 
$current_questi on = 

$thi s ->_currentQuesti onStri ng ( ) ; 
$previ ous_questi on = 

$thi s ->_previ ousQuestionString( ) ; 
$game_state = 

$thi s->_gameStateStri ng( ) ; 
$i ntroducti on = 

$thi s ->_gameText->i ntroduction( ) ; 
$ rul es = 

$thi s ->_gameText->rul es ( ) ; 
if ( $thi s->_game->getGameLost( ) ) ( 
$left_side = 

$thi s ->_gameText->game Lost Text ( ) . 
$thi s ->_hi ghScoreString( ) ; 



elseif ( $thi s ->_game->getGameWon ( ) ) { 
$left_side = 

$thi s->_gameText->gameWonText( ) . 
$this->_highScoreString( ) ; 

1 

else ( 

$left_side = $current_questi on ; 

I 

if ( $thi s ->_game->get Previ ous Quest i on ( ) ) ( 
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$right_side = 
"<TABLEXTRXTD> 
$previous_question 
</TDX/TRXTRXTD> 
$game_state 
</TDX/TRXTRXTD> 
$ rul es 

</TDX/TRX/TABLE>" ; 

) 

else ( 

$right_side = 

"<TABLEXTRXTD> 
$ introduction 
</TDX/TR> 
<TRXTD> 
$ rul es 

</TDX/TRXTRXTD> 
$game_state 
</TDX/TR> 
</TABLE>" ; 

} 

// actually construct page 

$page_string = <<<E0T 

$topjiatter_stri ng 

</H2X/CENTER> 

<TABLE B0RDER=2> 

<TR> 

<TD VALIGN=TOP WIDTH=40% >$1 ef t_si de</TD> 

<TD VALIGN=TOP WIDTH=60% >$ ri ght_s i de</TD> 

</TRX/TABLE> 

</BODYX/HTML> 

EOT; 

return ( $page_stri ng ) ; 

1 

} 

function handl eHi ghScore () { 

// Handles database update for case where player 
// has earned high score, and has submitted 
// a name for the record 
if ( ! $thi s ->_hi ghScorePosted ) ( 
$this->„highScorePosted = TRUE; 
if (get_post_value( 'NICKNAME' ) && 

get_post_val ue( ' ANSWER_COUNT ' ) && 
get_post_val ue( 'CREDIT' ) && 
get_post_val ue( 'CHECKSUM' ) U 
$thi s ->_c hecks umC hecks ( 

get_post_val ue( ' ANSWER_COUNT ' ) , 
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get_post_val ue( 'CREDIT' ) , 
get_post_val ue( 'CHECKSUM' )) ) ( 
$name = get_post_val ue( ' NICKNAME ') ; 
$answer_count = get _post_val ue( ' ANSWER^COUNT ' ) ; 
$ credit = get_post_val ue( ' CREDIT' ) ; 
Iconnection = 

$thi s ->_game->gamePa rameters ->getDbConnect i on ( ) ; 
$safe_name = my sql_rea 1 _escape_stri ng ( $name ) ; 
$safe_ans = mysql _rea l_escape_st ri ng ( $answer_count ) ; 
$saf e_credi t = mysql _real_escape„st ri ng ( $credi t ) ; 
$query = "insert into hi gh„s cores 

(name, answer_count , credit) 
val ues 

( ' $saf e_name ' , '$safe_ans', ' $saf e„credi t ' ) " ; 
$result = mysql_query ( $query , Iconnection); 

} 

else ( 

// do not hi ng- -f a i 1 ure to add high score 
// should not be a deal killer 
// really don't even need the else condition 
// but if you do, here's where it would go. 




// PRIVATE FUNCTIONS 

private function _makeTopMatter ( $ t i 1 1 e ) ( 
// returns HTML fragment that heads both 
// regular page and error page, containing 
// HTML head and title 
$return_stri ng = <<<E0T 

<HTMLXHEADXTITLE>$title</TITLEX/HEAD> 

<B0DY BGCOLOR=#FFFFFFXC ENTER) 

<Hl>$title<BR> 

<F0NT SIZE — 1 C0L0R=BLUE> 

(How sure <B>are</B> you?X/F0NT> 

</HlX/CENTER> 

EOT; 

return ( $ return_st ri ng ) ; 

} 

private function _currentQuestionString () { 

return( "<H2>" . 

$thi s->_game->getCurrentQuesti onText( ) . 
"</H2>" . 

"<F0RM METH0D=P0ST ACTI0N=\ " i ndex . php" >" . 
"<INPUT TYPE=HIDDEN NAME=POSTCHECK VALUE=1>" . 
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$thi s - >„d i stractorString( 

$thi s ->_game->getCur rentQuesti on ( ) ) . 
"</F0RM>" ) ; 

} 

private function _di stractorStri ng ($question) ( 
// creates the actual HTML for presentation of 
// radio-button alternatives for guesses. 
// Assumes that the array representing the 
// actual alternatives has been calculated in 
// advance, retrievable from the question using 
// getDi stractorArray 

$di stractor_array = $questi on->getDi stractorArray () ; 
$distractor_string = " <TAB LEXTR VALIGN=TOPXTD>" ; 
$di stractor_stri ng .= 

"<TABLE B0RDER=1 BGC0L0R=\ "#AAAAFF\ "><TRXTH> 
</THXTH>At 1 east</THXTH>Not more than</TH>"; 
$count = 1; // 1-based labels are preferable, 

// so we can just use if ( $ 1 a be 1 ) ... 
$total = count($di stractor_array ) ; 
foreach ( $di stractor_array as $distractor) ( 
$1 ower_sel ected = ($count == 1) ? 

"CHECKED" : ""; 
$upper_sel ected = ($count == $total ) ? 

"CHECKED" : ""; 
$f ormatted_di stractor = 
(Idistractor >= 10000) ? 

number_f ormat ( $di stractor ) : Idistractor; 
$di stractor„stri ng .= 

"<TRXTD>$formatted_di stractor</TD> 

<TDXINPUT T Y P E= RAD 1 0 NAME=\ " 1 ower\ " 
VALUE=$count 

$1 ower_sel ected ></TD>\n" . 
"<TDXINPUT T Y P E= RAD 1 0 NAME=\ " upper\ " 
VALUE=$count 

$upper_selected X/TDX/TR>\n" ; 
$count++; 

} 

$di stractor_stri ng .= "</TABLE>"; 
$di stractor_stri ng .= "</TDXTD>"; 
$di stractor_stri ng .= 

"<INPUT NAME=\"Submit guess\" VALUE=\"Submit guess\" 
TYPE=SUBMIT>" ; 
$distractor_string .= "</TDX/TRX/TABLE>" ; 

return($distractor_string) ; 
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private function _previ ousQuesti onStri ng () ( 
if (! $thi s ->_game->getPrevi ousQuesti on () ) ( 
$return_stri ng = " " ; 

} 

else ( 

$return_stri ng = 

$thi s ->_game->previ ousQuesti onCorrectO ? 
$thi s ->_ri ghtSt ri ng ( ) : 
$thi s ->_wrongStri ng ( ) ; 

} 

return ( $ return_st ri ng ) ; 



function _rightString () ( 

return ( "<H IX FONT CO L0R=GREEN> RIGHT ! </ F0NTX/H1> " ) ; 

} 

function _wrongString () ( 

return ( "<H IX FONT C0L0R=RED>WR0NG ! </ F0NTX/H1> " ) ; 

} 

private function _highScoreEligible () { 

// takes a game-ending score, and queries the 
// DB to see if the player is eligible for the 
// high score 1 i st 

$query = "select name, answer_count , credit 
from hi gh_s cores 

order by answer_count desc, credit desc 
limit 10" ; 
$connection = 

$thi s ->_game->getDbConnect i on ( ) ; 
if ($connection && i s_resource( $connecti on ) ) I 
$result = mysql_query ( $query , $connecti on ) ; 
$el i gi bl e = f al se ; 
if (my sql _num_rows ( Sresul t ) > 9) ( 

while ($row = mysql_fetch_assoc( $resul t) ) { 
$answer_count = $row[ ' answer_count ' ] ; 
$credit = $row[ ' credi t ' ] ; 
if ( ( $thi s ->„game- >getCor rect Answers ( ) 
> $answer_count ) | 
( ( $thi s ->_game->getCor rect Answer s ( ) 
== $answer_count ) && 
( $thi s->_game->_credi t > $credit))) ( 
leligible = TRUE; 
break ; 

1 

) 

1 
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else ( 

$el igible = TRUE; 

} 

return ( $el igible) ; 

1 

else ( 

throw new 

Excepti on ( "Game display has no database connection"); 

1 

} 

// Checksum is calculated when posting a score 

// (comprised of a number of correct answers plus 

// credit remaining) and the checksum is compared with 

// the submitted scores. A first line of defense against 

// spoofing (unless, of course, the checksum scheme is 

// published in a book or something). 

private function _checksumChecks ( $answer_count , $credit, 

$checksum) 1 

return ( $checksum == 

$thi s ->_ma keCheckSum( $answer„count , $credi t ) ) ; 

1 

private function _makeChecksum ( $answer_count , $credit) ( 
return (( round ( $credi t ) ) * 17) * 
( $answer_count * 31); 

} 

private function _postHighScoreString () { 

// The greeting plus HTML form for actually submitting 
// a name to the high scores list 
global $PHP_SELF; 

$answer_count = $thi s - >_game->getCor rectAnswers ( ) ; 
$credit = $thi s->_game->getCredi t( ) ; 

$checksum = $thi s->_makeChecksum( $answer_count , $credit); 
$resul t_stri ng = 

"<H2>Congratulations! You have a high score</H2>". 

"Enter your name (or a nickname) for the high ". 

"scores list:". 

"<F0RM METH0D=P0ST ACT 1 0N = \ " $ PH P_S E L F\ " >". 
"<INPUT NAME=NICKNAME TY PE=TEXT SIZE = 30>". 
"<INPUT NAME=ANSWER_COUNT TY PE=H I DDEN ". 

"VALUE=$answer_count>" . 
" < INPUT NAME=CREDIT TYPE=HIDDEN ". 

"VALUE=$credit>" . 
"<INPUT NAME=CHECKSUM TY PE=H I DDEN ". 

"VALUE=$checksum>" . 
"<INPUT NAME=Submit TYPE=SUBMIT ". 

"VALUE=Submit >" . 
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"<INPUT TY PE=H I DDEN NAME=POSTCHECK VALUE=1>" . 
"<INPUT TY PE=H I DDEN NAME=HIGHSCORE VALUE=1>" . 
"<FORM>" ; 
return($resul t_stri ng ) ; 

} 

private function _highScoreString () ( 

// The table of high scores itself, including 
// the database interaction necessary to retrieve it 
if ($this->_highScoreEligible() U 
! $thi s ->_hi ghScorePosted ) { 
$resul t_stri ng = $t hi s ->_postHi ghScoreSt r i ng ( ) ; 

1 

else ( 

$resul t_stri ng = " " ; 

) 

$resul t_stri ng .= 

"<H2>High scores to date</H2>". 

"<TABLE BORDER=lXTRXTH>Rank</TH>" . 

"<TH>Name</THXTH>Correct answers</TH>" . 

"<TH>Credit left at end</THX/TR>" ; 
Iquery = "select name, answer_count , credit 
from high_scores 

order by answer_count desc, credit desc 
limit 10"; 
$connection = 

$thi s - >__game->gameParameters ->getDbConnect i on ( ) ; 
if (Iconnection && i s_resource( Sconnecti on ) ) ( 
Sresult = mysql_query ( $query , Iconnection); 
$rank = 1 ; 

while ($row = mysql_f etch_assoc ( $ resul t ) ) ( 
$name = $row[ ' name ' ] ; 
$answer_count = $row[ ' answer_count ' ] ; 
$credit = (int) ($row[ 'credit ']) ; 
Iresul t_stri ng .= 

"<TRXTH>$rank</THXTD>$name</TD>" . 

"<TD>$answer_count</TDXTD>$credi t</TDX/TR>" ; 
$ ran k++ ; 

} 

$resul t_stri ng .= "</TABLE>"; 
return($result_string) ; 

) 

else ( 

throw new 

Excepti on ( " Game display has no database connection"); 

) 

} 

private function _gameStateStri ng () { 
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// The HTML table 

$correct_answers = $thi s->_game->getCorrectAnswers ( ) ; 
$credit = round_to_di gi ts ( $thi s->_game->getCredi t ( ) , 2); 
$level = $thi s->_game->getLevel ( ) ; 
return ("<TABLE CELLPADDING=10>" . 
"<TR BGCOLOR=$thi s->_bl ueCol or>" . 
"<TH>Total correct answers : </TH>" . 
"<TD>$correct_answers</TDX/TR>" . 

"<TR BGCOLOR=$this->_redColorXTH>Credit remai ni ng : </TH>" . 

"<TD>$credit</TDX/TR>" . 

"<TR BGC0L0R=$thi s->_bl ueCol or>" . 

"<TH>You have reached 1 evel : </TH> " . 

"<TD>$level</TDX/TRX/TABLE>") ; 

} 

} 

?> 



Note that in the GameDi spl ay class we use some object-oriented constructs that were new as of 

PHP5. The constructor function is called cons t ruct ( ) , rather than having the same name as 

the class. And we have designated the functions that are not intended for external use as private, 
which will prevent any such use by other classes. 

Most of the class's private functions involve querying the Game object for information that it then 
wraps up in HTML strings. One of the more interesting functions of this type is d i s t r a c t o r_ 
stri ng ( ) , which creates the actual display of alternatives for the answer range. The general divi- 
sion of labor here is: 

■ The upper and lower bounds for the answer are specified in the database, as well as how 
many choices should be displayed and how they should be scaled. 

■ The Questi on object takes this information and creates all the intermediate steps of the 
answer range as it is constructed. 

■ The GameDi spl ay object queries the game for the current question and then queries that 
question to discover the upper and lower bounds and the intermediate steps. It then sim- 
ply wraps those values in HTML to present radio button alternatives, with the maximum 
answer range preselected. 

game_text_class.php 

Your humble authors try really hard to make this stuff interesting, but in this case, we must declare 
defeat. The GameText class just wraps up some boilerplate HTML into member functions so that the 
GameDi spl ay class can ask for it. Enough said? 

The functions use our favorite technique for creating large chunks of boilerplate, which is the 
heredoc syntax. (See Chapter 7 for more on the uses of heredoc.) Listing 44-3 shows the game 
_text_cl ass . php. 
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game_text_class.php 

<?php 

class GameText 
{ 

function construct () { 

// no vars, nothing for constructor to do 

) 

function introduction () ( 
$intro = <<<E0T 

<H2>Welcome to the Certainty Quiz!</H2> 
The game that tests 

<LI>how much you know about how much <B>and</B> <LI>how much you 

know about how much you know about how much! 

<H4>The object</H4> The goal is to answer as many questions 

correctly as possible. 

Answer questions 

(starting with the first one at the left), by choosing 
values above and below where you think the right answer lies. 
Answers are correct if they include the real answer in the 
range . 

The narrower your guesses, the longer you'll survive. 
There are ten levels; if you think the questions are 
too easy, keep going. 
EOT; 

return($intro) ; 

) 

function rules () { 

$rules = <<<E0T 

<H4>Rules and scoring</H4> 

<LI>Four points subtracted from your credit for every incorrect 
answer . 

<LI>0ne point added to your credit for every correct answer, 
minus a penalty for the range of your answer. Specifying the 
entire range possible subtracts four points (for a total of -3); 
specifying a single step of the range subtracts nothing 

(for a total of +1). Intermediate ranges give intermediate re 
suits. 

<LI>Credit is capped at 15. 

<LI>Whenever your credit falls below zero, the game is over. 
EOT; 

return ( $ rul es ) ; 

} 

function gameLostText () { 
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global $PHP_SELF; 
$game_over = <<<E0T 
<Hl>Thanks for pi ayi ng ! </Hl> 

Thanks for taking the certainty quiz, and for being 

such a good <F0NT C0L0R=RED>L0SER! </F0NTXBR> 

<F0RM METH0D=P0ST ACT 1 0N = " $ PH P„S E LF " > 

<INPUT TYPE=SUBMIT NAME=N EW VALUE="New Game"> 

<INPUT TYPE=HIDDEN NAME=POSTCHECK VALUE=1> 

</F0RM> 

EOT; 

return ( $game_over ) ; 

} 

function gameWonText () { 
global $PHP_SELF; 
$game_over = <<<E0T 
<Hl>You won!</Hl> 

Thanks for taking the certainty quiz, and for 
beating it. We bow to your superior knowledge 
of what you know, and what you don't know. 
<F0RM METH0D=P0ST ACT 1 0N = " $ PH P_S E LF " > 
<INPUT TYPE=SUBMIT NAME=N EW VALUE="New Game"> 
<INPUT TYPE=HIDDEN NAME=POSTCHECK VALUE=1> 
</F0RM> 
EOT; 

return($game_over) ; 

} 

} 

?> 



game_class.php 

In this section, we get to the basic logic of the game. The Game object contains everything worth 
remembering about the current state of the game, as well as methods for updating it. 

Data members 

It's worth listing the important pieces of data that the Game object tracks: 

■ The current question (an instance of class Questi on) 

■ The previous question, if any (an instance of class Question) 

■ The questions that have been asked at this level (an array of database IDs) 

■ The questions that could still be asked at this level (an array of database IDs) 

■ The game's numerical defaults (an instance of class GameParameters) 

■ Numerical variables that track the game's state (credit, questions answered, and so on) 
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Public functions 

As with the GameDi spl ay class, let's list the functions that the Game class exposes to callers: 

■ The constructor function. 

■ Various accessor functions for member data. 

■ updateWithAnswerO takes the player's upper and lower guesses and updates the game's 
state accordingly, including both update of scores and setting up the next question to be 
asked. 



Database interaction 

The actual questions and answers that the game displays are retrieved from a backend MySQL data- 
base. There are two main types of interaction with that database: 

■ Whenever the player moves to a new level (including the first one), the Game object 
retrieves the IDs of all questions that may be asked at that level and scrambles their order- 
ing. This randomized list is propagated along with the Game object from page to page 
within a particular level of the game. 

■ Whenever a new question is actually ready to be asked, the Game object pops its database 
ID off the list constructed and then queries the question database to retrieve all the rest of 
the question's information (the text of the question, the correct answer, the range of pos- 
sible values to present, and so on). 

Listing 44-4 shows game_class.php. 



LISTING 44-4 



game_class.php 

<?php 

i ncl ude_once( "certai nty_uti 1 s . php" ) ; 

i ncl ude_once ( " game_pa rameters_cl ass . php" ) 

include_once("question_class.php"); 

class Game 



pu 
pu 



bl 


i c 


bl 


i c 


bl 


i c 


bl 


i c 


bl 


i c 


bl 


i c 


bl 


i c 



JULL; 
NULL; 



0.0; 



// an array of ids 
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public $_questi onsAs kedAt Level = 0; // a count 

public $_total Questi ons = 0; 

public $_correctAnswers = 0; 

public $_gamel_ost = FALSE; 

public $_gameWon = FALSE; 

// CONSTRUCTOR 

function construct () { 

$thi s->gameParameters = new GameParameters ( ) ; 
$thi s->_dbConnecti on = 

$this->gameParameters->getDbConnection( ) ; 
if ( ! $thi s->_dbConnecti on ) ( 

throw new Excepti on ( " No database connection"); 

1 

else ( 

$ t h 1 s->_correctAnswers = 0; 
$thi s->_l evel = 

$this->gameParameters->getStartingLevel ( ) ; 
$ t h i s->_credit = 

$this->gameParameters->getStartingCredit( ) ; 
// make a list of questions to be asked at the 
// starting level 
$thi s ->_setupQuesti on Ids ( ) ; 
// actually retrieve the first question 
$this->_installQuestion(); 

1 



// PUBLIC FUNCTIONS 
// accessors 

function getGameParameters( ) 

i return($this->game Parameters) ; ) 

function getCurrentQuesti on ( ) 

(return($this->currentQuestion) ; } 

function getPreviousQuestion( ) 

(return($this->previousQuestion);) 

function getCreditO ( return ( $thi s - >_credi t ); } 

function getLevel() { return ( $thi s->_l evel ); ) 

function getQuestionsAskedAt Level () 

(return($this- >_ques ti onsAsked At Level ) ; ) 

function getTotal Questi ons ( ) 

|return($this- >_total Questions) ; } 
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function getCorrectAnswers ( ) 

(return($thi s ->_c or rect Answers ) ; ) 

function getGamel_ost( ) 

{ return ($thi s ->__game Lost ) ; } 

function getGameWon() 

(return($thi s ->_gameWon ) ; ) 

function getCurrentQuesti onText ( ) ( 

if ( ! i s_object( $thi s->currentQuesti on ) ) { 
printC'What is it?<BR>"); 
pr i nt_r ($this->currentQuestion) ; 

} 

else ( 

return($this->currentQuestion->getQuestion()); 

) 

} 

function previ ousQuesti onCorrect( ) ( 

return($this->previousQuestion->getCorrect()); 

} 

function getDbConnecti on () ( 
if ( ! $thi s->_dbConnecti on ) { 
$thi s->_dbConnecti on = 

$this->gameParameters->getObConnection( ) ; 

} 

return ($t hi s ->_dbConnect i on ) ; 



function updateWi thAnswer (Slower, Supper) { 

// The main modifying function for a game object. 
// Takes a player's upper and lower guess, determines 
// correctness, updates scores, determines if the 
// player has graduated to the next level, and 
// swaps in the next question. 

$thi s->previ ousQuesti on = $thi s->currentQuesti on ; 
$thi s->previ ousQuesti on ->updateWith An s we r($lower, 

Supper ) ; 

$thi s->_updateScores( ) ; 
$thi s->_maybeChange Level ( ) ; 

if ( ! ( $thi s->_gameLost || $thi s->_gameWon ) ) ( 
$thi s - >_i nstallQuestion(); 

) 



// PRIVATE FUNCTIONS 

function „installQuestion () { 
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// actually retrieve a question from the database 
// and create a corresponding instance of Question 
if ( count ( $thi s ->_questi on IdsAt Level ) > 0) I 
// pop a question off the randomized list 
$question_id = 

array_pop( $ t h i s->_questi onlds At Level ) ; 
$query = 

"select id, question, answer, 
upper_limit, lower_limit, scaling_type 
from question 
where id = $questi on_i d" ; 
if ( ! $thi s ->_dbConnecti on ) ( 
$thi s->_dbConnecti on = 

$this->gameParameters->getDbConnection( ) ; 

} 

if ( $thi s->_dbConnecti on && 

is_resource($thi s->„dbConnecti on ) ) ( 
$result = mysql_query ( $query , 

$thi s->__dbConnecti on ) ; 
if ($row = my sql_f etch_assoc ( $ resul t ) ) { 
$thi s->currentQuesti on = 
new Quest ion( 
$row[ 'id'], 
$row ['quest ion'], 
$row[ ' answer ' ] , 
$ row[ ' 1 ower_l i mi t ' ] , 
$ row[ ' upper_l i mi t ' ] , 
10, 

$row[ ' seal i ng_type ' ] ) ; 
$thi s->„questi onsAskedAt Level ++; 

} 

else { 
throw new 

Except i on (" Probl em retrieving question from database"); 
) 

) 

else ( 

throw new 

Excepti on ( " Probl em querying question database"); 

) 

} 

else ( 

throw new 

Excepti on (" Coul d not find any questions to ask"); 

1 

} 

function _setupQuesti on Ids () { 
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$thi s ->_questi on IdsAtLevel = 

$thi s - >_getQuesti onlds At Level ($thi s->_l evel ) ; 

} 

function _getQuesti onldsAtLevel ($level) ( 

// to be used at time of graduation to a new level - 
// retrieves the new ids (only) of all questions at 
// the level, and shuffles them into a random order. 
$return_array = arrayO; 
$query = "select id from question 

where level = $level"; 
$this->getDbConnection( ) ; 
if ( ! $thi s ->_dbConnecti on ) { 
throw new 

Except i on (" No database connection"); 

) 

el se { 

$result = mysql_query($query, 

$thi s ->_db Connect i on ) ; 
while ($row = mysql_f etch_assoc ( $ resul t ) ) ( 
a rray_pus h ( $ ret urn_a rray , $ row[ ' i d ' ] ) ; 

1 

) 

// randomize the order of the questions 

$return_array = create_randomi zed_a rray ( $return_a r ray ) ; 

return ($ return_a rray ) ; 



public function _updateScores () ( 

// Change the current score based both on 
// whether the player got the answer right and on 
// the spread between the player's upper and lower 
// guess. Calculations depend on settings from 
// the GameParameters class, 
if ( $thi s ->previ ousQuest i on ->ri ghtAnswer ( ) ) { 
$thi s->_correctAnswers = 

$thi s->_correctAnswers + 1; 
$thi s->_credi t += 

$this->gameParameters->getRi ghtAnswerCredi t ( ) - 
($this->previ ousQuest ion->getAnswerSpread( ) * 
$this->gameParameters->getAnswerSpreadDebit()); 

} 

else ( 

$new_credit = 
$thi s->_credi t = 
$thi s->_credit - 

$this->gameParameters->getWrongAnswerDebit( ) ; 

} 
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// enforce cap on credit 
$thi s->_credi t = 
mi n ( $thi s ->_credi t , 

$this->gameParameters->getMaximumCredit()); 

} 

function _maybeChangeLevel () { 
if ($this->_credit < 0.0) { 
$thi s->_gamel_ost = TRUE; 

I 

else ( 

Iparams = $thi s->gameParameters ; 
$current_J evel = $thi s->_l evel ; 
if ( $current_l evel > 

$params->getMaximuml_evel ( ) ) { 
$thi s->_gameWon = TRUE; 

) 

else ( 

// find out if questions remain to be 

// asked at this level 

if ( ( $thi s->_questi onsAskedAtLevel >= 

$params->getQuestionsPer Level ( $current_l evel ) ) | 
(count($this->_questionIdsAtLevel ) == 0)) { 
// either we have asked the limit of 
// questions per level, OR we have simply run out 
$thi s->_l evel++; 

$thi s ->_questi onsAs kedAt Level = 0; 

$thi s ->_setupQuesti on I ds ( ) ; 

// note recursive call — it's possible 

// that no questions were found, and we have 

// to keep going 

$thi s->_maybeChange Level ( ) ; 



f uncti on si eep ( ) ( 

// make sure to serialize all fields except 
// the database connection (has to be recreated) 
// and the previous question (no point), 
return ( a r ray ( 

' gamePa rameters ' , 

' currentQuesti on ' , 

'_credi t ' , 

'_! evel ' , 

'_questi on IdsAt Level ' , 
'_questi onsAskedAtLevel ' , 
'_correctAnswers ' , 
'_total Questi ons ' , 
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'_gamel_ost ' 
'„gameWon ' ) 



?> 



Handling an answer 

Here are the steps that a Game object goes through in dealing with a guess range submitted by a 
player (in the function updateWi thAnswer): 

1. Move the current question object to the previous question slot. 

2. Update the (now previous) question with the upper and lower ranges of the guess (which 
are still in terms of step numbers from the form rather than actual values). 

3. Query the previous question to discover the range of the guess and whether the question 
was correctly answered. Update all scores (credit, correct answers) appropriately. 

4. Decide whether to promote the player to a new level now. If so, retrieve the database IDs of 
all questions that may be asked at that level. Randomize the order of the question list. 

5. If the game has not yet ended, grab a new question ID from the randomized list and use it 
to ask the database for a new question. Turn that data into aQuestion object and make it 
the current question. 



Serialization and sleepO 

The s I eep ( ) function is called to do cleanup whenever an object is serialized and also returns a list 
of all the member variables that should be recorded in a serialization. The Game class makes use of 
only the latter capability — all member variables except the previous question and the database con- 
nection itself are retained as the object is stored in the session for the next page's use. 

game_parameters_class.php 

The single instance of the Game Para meters class, shown in Listing 44-5, packages up all the default 
numbers that we may want to customize in making a new version of the game (the penalties and 
rewards, the number of levels, the starting and maximum credit, and so on). In addition, this object 
manages global access to the database connection. 



LISTING 44-5 



game_parameters_class.php 

<?php 

i ncl ude_once( "certai nty_uti I s . php" ) ; 
include_once("dbvars.php"); 
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class GameParameters ( 



va r 


$_dbConnecti on = NULL; 


va r 


$_starti ngLevel = 1; 




va r 


$_maxi mumLevel = 10; 




va r 


$_starti ngCredi t = 5. 


0; 


va r 


$_maximumCredi t = 15. 


0; 


va r 


$_questi onsPerLevel = 


3; 


va r 


$_ri ghtAnswerCredi t = 


1.0 


va r 


$_wrongAnswerDebi t = 


4.0; 


va r 


$„answerSpreadDebi t = 


4.0 



// CONSTRUCTOR 

function GameParameters () j 

// all fields set by default values 

} 

// PUBLIC FUNCTIONS 
// accessors 

function getStarti ngLevel () ( 
return ($thi s ->_sta rti ngLevel ) ; 

} 

function getMaxi mumLevel () { 
return($thi s->_maxi mumLevel ) ; 

1 

function getSta rt i ngCredi t () { 
return ( $thi s ->_sta rti ngCredi t ) ; 

} 

function getMaxi mumCredi t () { 
return ($thi s ->_maxi mumCredi t ) ; 

1 

function getRi ghtAnswerCredi t () { 
return ( $thi s ->_ri ghtAnswerCredi t) ; 

} 

function getWrongAnswerDebi t () ( 
return ($thi s ->_wrongAnswerDebi t ) ; 

} 

function getAnswerSpreadDebi t () ( 
return ($thi s ->_ans we r Spread Deb i t ) ; 

} 
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function getQuesti onsPerLevel () ( 
return ($t hi s ->_quest i onsPerLevel ) ; 

} 

function getDbConnecti on () 1 

global $host, $user, $pass, $db; // from dbvars.inc 
if ( $thi s ->_dbConnecti on && 

i s„resource ( $this->dbConnection)) { 
return ( $_dbConnecti on ) ; 

} 

else ( 

// suppress warnings about connection, 
// will handle at higher level if failed 
$connection = 

@mysql_connect( $host , $user, $pass); 
if ($connection && 

my sql _sel ect_db ( $db , $connection)) { 

return ( $connecti on ) ; 

} 

else ( 

return( FALSE) ; 

1 

) 

} 

f uncti on si eep ( ) I 

return(array( '_sta rti ngLevel ' , 
'_sta rti ngCredi t ' , 
'_ri ghtAnswerCredi t ' , 
'_wrongAnswerDebi t ' , 
'_answerSpreadDebi t ' , 
'_questi onsPerLevel ')); 

1 

} 

?> 



certainty_utils.php 

This code file, shown in Listing 44-6, is a grab-bag for capabilities and definitions that do not fit 
neatly into a particular class and that are used in more than one other code file. 

Everything in certa i nty_uti 1 s . php fits into one of a few categories: 

■ Initial declarations (seeding the random number generator, setting the error-reporting level). 

■ Abstraction functions for session and post variables. 

■ Utility functions for calculating intermediate answer values and for randomizing question lists. 
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LISTING 44-6 



certainty_utils.php 

<?php 

// Definitions and utility functions for the 
// Certainty Quiz game 
error_reporti ng ( E_ALL ) ; 

// enumeration constants for the scaling of distractors 
def i ne( "CERTAINTY_LINEAR" , 1) ; 
def i ne( "CERTAINTY„GEOMETRIC" , 2) ; 

// Seed the random number generator 
srand( (doubl e) microtimeO * 1000000); 

// A hack to retrieve the value of POST values 
// without explicitly checking PHP versions, 
function get_post_va 1 ue ($var_name) ( 
global $HTTP^.P0ST_VARS; 
if ( IsSet($_P0ST) && 

IsSet($_P0ST[$var_name] ) ) { 
return ( $_P0ST[$var_name] ) ; 

} 

elseif ( IsSet($HTTP_P0ST_VARS) && 

IsSet($HTTP_POST_VARS[$var_name] ) ) ( 
return($HTTP_P0ST_VARS[$var_name] ) ; 

1 

else { 

return( FALSE) ; 

1 



function get_sessi on_val ue ( $va r_name ) I 
global $HTTP_SESSI0N_VARS; 
if ( IsSet ( $„SESSI0N ) && 

IsSet($_SESSI0N[$var_name] ) ) ( 
return ( $_SESSI0N[$var_name] ) ; 

} 

elseif ( IsSet($HTTP_SESSI0N_VARS) && 

IsSet($HTTP„SESSION_VARS[$var_name]) ) { 
return ( $HTTP_SESS I0N_VARS [ $ va r_name] ) ; 

1 

else ( 

return( FALSE) ; 

1 



function set_sessi on_val ue ( $var_name , lvalue) I 
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global $HTTP_SESSION_VARS; 
if (IsSet($_SESSION)) { 

$_SESSION[$var_name] = lvalue; 

$HTTP_SESSION_VARS[$var_name] = lvalue; 

1 

else j 

$HTTP_SESSION_VARS[$var_name] = lvalue; 

} 



function unset_sessi on_val ue ($var_name) I 
if (IsSet($_SESSION[$var_name])) { 
$„SESSION[$var_name] = " ; 
unset($„SESSION[$var_name] ) ; 

1 

} 

// Numerical functions 

function round_to_di gi ts ($number, $digits) { 
if ($number < 0) ( 

return(- round_to_di gi ts ( - $number, $digits)); 

} 

else if ( $number == 0 ) ( 
return ( $number ) ; 

} 

else { 
$tens = 

floor(loglO($number)); 
$divisor = powdO, ($tens - Idigits)); 
$significant = (1.0 * $number) / 

$ d i v i s o r ; 
$rounded = round($significant); 
return ($ rounded * $divisor); 

} 



function nth_root_i ni ti al ( $product , $n) 

{ 

Sestimate = sqrt ( $product ) ; 

$roots = 2; 

while ($roots < $n) I 

lestimate = sqrt( Sestimate) ; 

Iroots = $roots * 2; 

} 

return($estimate) ; 



function nth_root ($product, $n) ( 
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if ((Sproduct <= 1) | | 
($n < 2)) { 
di e ( "Arguments to nth_root should be ". 
"product (greater than 1) and " . 
" n (greater than 1)"); 

1 

$i ni ti al_estimate = 

nth_root_i ni ti al ( Sproduct , $n); 
return ( nth_root_aux( Sproduct, $n, 

$i n i ti al_est i mate , 

20000, 

0.0001 ) ) ; 



function nth_root_aux (Sproduct, $n, 

$guess , 

$i terati ons_l eft , 
$desi red_di fference) ( 
if (literationsjeft <= 0) ( 
return ( $guess ) ; 

1 

else ( 

$guessed_product = pow($guess, $n); 
if ( abs ( $guessed_product - Sproduct) 
< $des i red_di fference ) ( 
return ( $guess ) ; 

} 

else ( 

$new_guess = 
$guess - 

( ( pow( $guess , $n) - Sproduct) / 
( $n * pow( Iguess , $n-l ) ) ) ; 
return ( nth_root_aux( Sproduct, $n, 
$new_guess , 
$i terati ons_l eft - 1, 
Ides i red_di fference)); 




function create_randomi zed_array ($in_array) ( 
// Assumes input is simple list, with keys 
/ / equal to 0 , . . . , n 

// Returns similar list, with keys as in input 

// but values in randomized order 

// Assumes prior call to srand() 

$i n_array_l ength = count ( $i n_a r ray ) ; 

$worki ng__array = array(); 

for ($i = 0; $i < $ i n_a rray_l ength ; $i++) { 
$rand_val ue = rand( ) ; 
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$worki ng_array [$i ] = $rand_val ue ; 

} 

asort ( $worki ng_a r ray ) ; // orders by random value 
$return_array = array(); 

$worki ng_keys = a rray_key s ( $wor ki ng_a r ray ) ; 
foreach ( $worki ng_keys as $int_key) ( 
array_push( $return_array , 
$i n_array [$i nt_key] ) ; 

} 

return ( $ return_a r ray ) ; 

} 

?> 



The functions in certai nty_uti 1 s . php take care of figuring out all the intermediate guesses 
between the lowest value offered to the user and the highest value. In addition, there's a scaling 
option, which determines whether the intermediate values grow linearly or geometrically. (If you 
think that the number "between" 10 and 1000 is 100, you are scaling geometrically; if you think the 
number between 10 and 1000 is 505, you are scaling linearly.) The functions for finding nth roots 
are used in doing the geometric scaling. 

The crea te_randomi zed_a rray ( ) function is what we use to scramble the order of questions 
within a level. 

question_class.php 

Finally, we get down to the actual questions that are pulled from our database of questions to ask. 
The definition of the Question class is shown in Listing 44-7. The public functions here are: 

■ The constructor, which is given the question, correct answer, the upper and lower bounds, 
the number of steps in the guesses, and the type of scaling (linear or geometric). 

■ Various accessor functions, such as getAnswer( ), getQuestion( ), getScal ingType( ). 

■ updateWithAnswerO, which bottoms out here by actually translating the Web form's 
step numbers to values for the guesses, comparing those guesses to the real answer. 

■ getAnswerSpreadO, which returns a measure of how narrow the guess was . 



LISTING 44-7 



question_class.php 

<?php 

i ncl ude_once( "certai nty_uti 1 s . php" ) ; 

class Question 
{ 

// PRIVATE VARIABLES 

private $_id; // ID in database 
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private $_question; // text of question 

private $_answer; // correct numeric answer 

private $_1 owerLimi t ; // smallest value in abstractors 

private $_upperl_imi t ; // largest value in abstractors 

private $_di stractorCount ; // number of dist. presented 

private $_scal i ngType ; // representing linear vs. geometric 

private $_di stractorArray ; // contains all dist presented 

private $_lowerGuess = NULL; // player's lower bound 

private $_upperGuess = NULL; // player's upper bound 

private $_correct = NULL; // TRUE or FALSE after guess 

// CONSTRUCTOR 

function construct! $i d , $question, 

Sanswer , 

$1 ower_l imi t , 

$upper_l i mi t , 

$di stractor_count , 

$scal ing_type) ( 

$this->_id = $id; 

$thi s->_questi on = Squestion; 

$thi s->_answer = $answer; 

$thi s->_l owerLimi t = $1 ower_l i mi t ; 

$thi s->_upperLimi t = $upper_l i mi t ; 

$thi s->_di stractorCount = $di stractor_count ; 

$thi s->_scal i ngType = $scal i ng_type ; 

$thi s->_di stractorArray = 

$thi s ->_ma keDistractors($l ower_l i mi t , 

$upper_l Inn" t , 

$di stractor_count , 

$scal i ng_type) ; 



// PUBLIC FUNCTIONS 



// accessors 



function getld () 1 return ( $thi s - >_i d ); I 

function getQuestion () ( return ( $thi s ->_questi on ); } 

function getAnswer () { return ( $thi s ->_answer ); ( 

function getCorrect() { return ( $thi s ->_correct ); ) 

function ri ghtAnswerC ) ( return ( $thi s ->_correct ); } 

function getDi stractorCount( ) { return ( $ t hi s ->_correct ); ) 

function getScal ingType( ) ( return ( $t hi s ->_sca 1 i ngType ); ) 

function getDi stractorArray ( ) 

lreturn($this- >_di stractorArray) ; ) 

function getLowerGuess( ) ( return ( $thi s ->_1 owerGuess ); } 

function getUpperGuess ( ) ( return ( $thi s ->_upperGuess ); } 

function getAnswerSpread () { 

$answer_range = count ( $thi s ->_di stractorArray ) - 1; 
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if ( I sSet ( $thi s - >_1 owerGuess ) && 

I sSet ( $thi s - >_upperGuess ) ) ( 
Slower = $thi s->_l owerGuess ; 
Supper = $thi s->_upperGuess ; 
if (Supper < Slower) ( 

throw new Excepti on ( " Probl em in range of answers"); 

} 

else ( 

Sspread = 

(max($upper - Slower, 1) - 1) 

/ ( Sanswer_range - 1 ) ; 
return ( Sspread ) ; 

1 

1 

else ( 

throw new Excepti on ( "Answer variables not set"); 

) 

} 

function updateWi thAnswer( $1 ower , Supper) ( 

// takes a lower and upper guess from player, and 

// determines if the guesses bound the right answer 

Sthi s ->_1 owerGuess = Slower; 

Sthi s->_upperGuess = Supper; 

$upper_value = NULL; 

$lower_value = NULL; 

Scount = 1; 

foreach ( Sthi s - >_d i stractorArray as Sdistractor) { 
if (Scount == Slower) ( 

$lower_value = Sdistractor; 

I 

if (Scount == Supper) ( 

$upper_value = Sdistractor; 

I 

$count++ ; 

) 

if ( I sSet ( $1 ower_val ue ) && IsSet( $upper_val ue) ) ( 
Sanswer = Sthi s->_answer ; 
SI ower_val ue_l owered = $lower_value - 

max(0.0001, abs ( SI ower_val ue / 1000000.0)); 
$upper_val ue_rai sed = $upper_value + 

max(0.0001, abs ( $upper_val ue / 1000000.0)); 
if (( SI ower_val ue_l owered <= Sthi s ->_answer ) && 
( Supper_val ue_rai sed >= Sthi s->_answer) ) { 
Sthi s->_correct = TRUE; 

I 

else ( 

Sthi s->_correct = FALSE; 

1 
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else ( 

$thi s->_correct = NULL; 

1 

1 

// PRIVATE FUNCTIONS 

private function jnakeDi stractors (Slower, Supper, 

$di stractor_count , 
$1 i nea r_or_geomet ri c ) 
// Create the array of intermediate values between 
// the upper bound and the lower bound on guesses 
// that the player can choose from. Depending on 
// a flag in each row of the question database, 
// the scaling of possible answers (" di stractors " ) 
// can be linear (10, 20, 30 ...) or geometric 
// ( 10, 20, 40, 80 ... ) 

// Code for construction of geometric distractors can 
// blow up for some arguments, so arguments are 
// checked before calls to make_di stractors_geometri c 
// are allowed. Failures default back to linear. 

{ 

if ( ($1 inear_or_geometric == CERTAI NTY_GE0METRI C ) && 
( $thi s->safeGeometri cArguments ( Supper , Slower))) { 
return ($thi s ->_makeDi stractorsGeometric( 
Slower, Supper, Sdi stractor_count ) ) ; 

I 

else ( 

return (Sthi s ->_ma keDistractorsLinear( 
Slower, Supper, Sdi stractor_count ) ) ; 

1 

} 

private function saf eGeometri cArguments (Supper, Slower) { 
// should probably really also include the number 
// of distractors as an argument. Only tested for 
// # of distractors approx 10. 
return ((Supper > 0) && (Slower > 0) && 

(Supper > Slower) && 

((Supper / Slower) < 10000000000)); 

} 

private function _ma keDi stractors Li nea r 

(Slower, Supper, Sdi stractor_count ) 

{ 

Sreturn_array = array(); 

a r ray_push ( $return_ar ray , round_to_di gi ts ( $1 ower , 3)); 
Scurrent = Slower; 

Sincrement = ((Supper - Slower) / Sdi stractor_count ) ; 
// add in all the intermediate values 
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for ($x = 1; $x < $di stractor_count ; $x++) { 
a r rayjush ( $return_array , 

round_to_di gi ts ( $1 ower + 

( $x * $i increment ) , 
3)); 

} 

a r ray_push ( S return_a rray , round_to_di gi ts ( Supper , 3)); 
return ($ return_a rray ) ; 



private function _makeDi stractorsGeometri c 

(Slower, Supper, Sdi stractor_count ) 

{ 

if ((Slower >= Supper) | 

( $di stractor_count < 2)) { 
die("Args to _ma keDi stractorsGeometri c should be " . 
"1) a lower limit, 2) an upper limit, " . 
"3) a count (>= 2) of divisions between them.<BR>" 
"Args were 1) Slower, 2) Supper, 3) Sdi stractor_count<BR>" ) 
) 

Sreturnjrray = array(); 

a r ray_push ( S return_a rray , round_to_di gi ts ( SI ower , 3)); 
$limit_ratio = Supper / Slower; 

Sroot = nth_root ( $1 i mi t_ra ti o , Sdi stractor_count ) ; 
Scurrent = Slower; 
// add in the intermediate values 
for ($x = 1; $x < Sdi stractor_count ; $x++) ( 
Sdistractor = round_to_di gi ts ( 

Slower * pow(Sroot, Sx), 
3) ; 

a r ray_push ( $ return_a r ray , 
Sdi stractor ) ; 

) 

a rray_push ( $ return_a rray , round_to_di gi ts ( Supper , 3)); 
return ( S return_a rray ) ; 



I 

?> 



dbvars.php 

When we actually query the database, we need to have access information. The file shown in 
Listing 44-8 is loaded by GamePa rameters . php and sets up the variables necessary for making a 
MySQL connection. Note that the current values are dummies and will not work on your system! You 
need to fill in the correct values for your own MySQL configuration. If your web server is connected 
to the Internet, it's also a good idea to move this file somewhere outside the web server document 
tree and to change the reference in GameParameters . php to point to its new location. 
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LISTING 44-8 



dbvars.php 



<?php 

$host = "YOUR_HOSTNAME" ; 

$user = "YOUR_MYSQL USERNAME" ; 

$pass = "YOUR_MYSQL_PASSWORD" ; 

$db = "certai nty" ; 
?> 



Creating the database 

The trivia game is fueled by a database of questions. So far, we have said nothing about how to cre- 
ate such a database. 



Table definitions 

Listing 44-9 shows a MySQL dump file of all the table definitions used in the code, along with a few 
sample entries. Before loading it, you need to create a database called certai nty; after that is done, 
you should be able to simply cat or pipe the contents of this file to the mysql command. 

Note that the question table includes several fields that are not actually used in the current code. 
One of them is attribution, useful for recording the book or web site that served as the authority 
for the answer. Another is include, which we intended for filtering out questions in development 
that were not ready to be displayed. A third is subjectID, which we use to tag questions accord- 
ing to subject area (Science, Geography, History, and so on), although that association is not actually 
displayed anywhere. A final as-yet unused column is un i 1 1 D, which could be used to record the 
unit (kilometers, years, furlongs, bushels) of the answer in case the unit affects how guesses should 
be displayed. 



LISTING 44-9 



Table definitions 

# MySQL dump 7.1 

# Host: [host deleted] Database: certainty 

# 

# Server version 3.22.32 



# Table structure for table ' hi gh_scores ' 
# 

CREATE TABLE high_scores ( 

id int(ll) NOT NULL auto_i ncrement , 
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name va rcha r ( 30 ) , 
answer_count int(ll), 
credi t doubl e( 16 ,4) , 
PRIMARY KEY (id) 

); 
# 

# Dumping data for table ' hi gh_scores ' 
# 

INSERT INTO high_scores VALUES (8, 'Ben Stei n ' , 15 , -3 . 0000 ) ; 
# 

# Table structure for table 'question' 
# 

CREATE TABLE question ( 

ID int(ll) NOT NULL auto^i ncrement , 
answer doubl e( 16 ,4) , 
unitID int(ll) , 
level int(ll), 
sub ject I D i nt ( 1 1 ) , 
include ti nyi nt (4) , 
upper_limit doubl e ( 16 , 4 ) , 
lower_limit double(16,4), 
scaling_type tinyint(4), 
question va rcha r ( 255 ) , 
attribution va rcha r ( 255 ) , 
PRIMARY KEY (ID) 

); 
# 

# Dumping data for table 'question' 
# 

INSERT INTO question VALUES 

(1,52837 55345.0000,1,1,1,1,200000000000.0000,1000000.0000,2, 
'What was the human population of the world 
in the middle of 1990?' , 

' http : //www . census. gov/i pc /www /wo rl dpop.html'); 

INSERT INTO question VALUES (2,70.0000,1,1,1,1,95.0000,5.0000,1, 
'What percentage of the EarthVs surface is covered by water?', 
' http : /www .sciencenet. org.uk/ database/Geography/ 
0riginal/g00057d.html ' ); 
INSERT INTO question VALUES 

(4, 1969. 0000, NULL, 1,2, NULL, 2000. 0000, 1950. 0000,1, 

'In what year did human beings first walk on the moon?',''); 

# 

# Table structure for table 'subject' 
# 

CREATE TABLE subject ( 
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id int(ll) NOT NULL auto_i ncrement , 
subject varchar(255), 
PRIMARY KEY (id) 

) ; 

# 

# Dumping data for table 'subject' 
# 

INSERT INTO subject VALUES ( 1 ,' Geography ') ; 
INSERT INTO subject VALUES ( 2 , ' Hi story ' ) ; 
INSERT INTO subject VALUES ( 3 , ' Sci ence ' ) ; 
INSERT INTO subject VALUES ( 4 , ' Mathemati cs ' ) ; 
INSERT INTO subject VALUES ( 5 , ' Mi seel 1 aneous ' ) ; 



The MySQL dump includes only three sample questions. You can always add more through a direct 
interaction with MySQL, but it's more convenient to do it via a Web form. 

entry_form.php 

Listing 44-10 shows a bare-bones Web form for entering more questions into the question database. 
This simply takes typed input (except for a pull-down association with the subject table) and trusts 
the results. Note that there is neither security nor error- checking here — this is intended for use 
only by the game creator, and if misuse is a concern you should probably add password protection 
or some other kind of authentication. (See Chapter 44 for more on creating authentication systems.) 



LISTING 44-10 



entry_form.php 

<?php 

incl ude_once( "certai nty_uti 1 s . php" ) ; 
i ncl ude_once( "game_parameters_cl ass . php" ) ; 
$params = new GamePa rameters ( ) ; 
$connection = $pa rams ->getDbConnect i on ( ) ; 

if (get_post_val ue( ' POSTCHECK' ) ) ( 
handl eEntry Form( ) ; 

} 

di spl ayEntry Form( ) ; 

function handl eEntry Form () 1 

$question = mysql_real_escape_st ri ng ( get_post_val ue( 'QUESTION')); 
$answer = my sql _real _escape_stri ng ( get_post_val ue (' ANSWER ')) ; 
$1 ower_l i mi t = mysql _real_escape_st ri ng ( get„post_val ue ( ' LOWE R_L I M I T ' ) ) ; 
$upper_l i mi t = mysql _real_escape_st ri ng ( get_post_val ue ( ' U P P E R_L I M I T ' ) ) ; 
$level = my sql_rea 1 _escape_stri ng ( get_post_va 1 ue (' LEVEL ')) ; 
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Ssubject = mysql_real _escape_stri ng ( get_post_va 1 ue( 'SUBJECT')); 
$ s c a 1 i ng_type = my sql _real _escape_st r i ng ( get_post_val ue ( ' SCALI NG_TYPE ' ) ) ; 
$attribution = my sql_real _escape_st ri ng ( get_post_val ue ( ' ATTRI BUT I ON ' ) ) ; 
if ( $upper_l i mi t > $1 ower_l i mi t ) ( 
$query = 

"insert into question 
(question, answer, lower_limit, upper_l i mi t , 
level, subjectID, sea 1 i ng_type , 
attribution) 
val ues 

( ' $questi on ' , $answer, $1 ower_J i mi t , $upper_l imi t , 
llevel, Isubject, $scal i ng_type , 
' Sattri buti on ' ) " ; 
Iresult = my sql _query ( $query ) ; 
if (Iresult) { 

print(" Entry was successful<BR>"); 

} 

else ( 

print("Entry was not successful <BR>" ) ; 

) 

1 

else { 

print("Upper limit must be greater than lower<BR>"); 

} 

} 

function di spl ay Entry Form () ( 

global $PHP_SELF; 

Slinear = CERTAI NTY_LI N EAR ; 

Sgeometric = CERTAI NTY_GEOMETRI C ; 

$subject_stri ng = ma ke_sub j ect_stri ng ( ) ; 

$f orm„stri ng = <<<E0T 

<F0RM METH0D=P0ST TARGET="entry_f orm. php" > 
Question: 

<I NPUT TYPE=TEXT NAME=QUESTION SIZE=60 ><BR> 
Answer : 

<I NPUT TYPE=TEXT NAME=ANSWERXBR> 
Lower : 

<INPUT TYPE=TEXT NAME=LOWER_LIMITXBR> 
Upper : 

<INPUT TYPE=TEXT NAME=UPPER_LIMITXBR> 
Level : 

<I NPUT TYPE=TEXT NAME=LEVELXBR> 
Subject : 

$subject__stri ng<BR> 
Scaling type : 

<SELECT NAME=SCALI NG_TY PE> 

<0PTI0N VALUE=$1 inear>Linear 

<0PTI0N VALUE=$geometric>Geometric 
</SELECTXBR> 
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Attn buti on : 

<INPUT TYPE=TEXT NAME=ATTRIBUTIONXBR> 
<INPUT TYPE=SUBMIT NAME=SUBMIT VALUE=SUBMIT> 
<INPUT TYPE=HIDDEN NAME=POSTCHECK VALUE=1> 
</F0RM> 
EOT; 

echo $f orm_stri ng ; 

} 

function make_subject_stri ng () { 

$result_string = "<SELECT NAME=SUBJ ECT> " ; 

$query = "select id, subject from subject order by id"; 

Sresult = my sql _query ( $query ) ; 

while ($row = my sql _f etch_row( $ resul t ) ) ( 

$i d = $row[0] ; 

$di spl ay = $row[l] ; 

$result_string .= "<0PTI0N VALUE=$id>$di spl ay" ; 

} 

$result_string .= "</SELECT>"; 
return($resul t_st ri ng ) ; 

} 

?> 



General Design Considerations 

What follows is a brief list of issues that we were forced to consider while writing the code in this 
chapter. 

Separation of code and display 

The question of separating code and display is a vexing one, especially in situations where you have 
different personnel assigned to maintaining logic and appearance. Our own view on this is that per- 
fect separation of code and display is like a perfect vacuum — you can get asymptotically closer to 
the ideal as you expend infinite effort. 

For large web sites employing many people, some pretty good techniques exist for making a strong 
separation, including templating systems and database storage of graphics and display text. For this 
relatively small and informal example, we were satisfied by simply segregating all HTML into two 
display-oriented classes, leaving the remainder of the code focused on logic and data. 

Persistence of data 

There are several kinds of data in this game that survive longer than the execution time of a page. 
We chose to use PHP's session mechanism for all the data particular to a particular game invocation 
and a backend database for everything else (questions, answers, and high score lists). 
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For reasons of efficiency, we didn't want to store too much data via the session mechanism. So we 
separated out the most important data (that could not be easily recreated) into the Game class and 
stored only an instance of that class. Everything else (question text, boilerplate HTML text, high 
scores, and so on) was either embedded in code files or easily retrievable from the database. 

Exception handling 

We used the new (as of PHP5) exception mechanism to bail out whenever we encountered a prob- 
lem that the code could not recover from. Failures to recover session info, failures to find cookies, 
and database interaction problems were all grounds for giving up. In general, when we threw an 
exception, we sent a string suitable for display to a user and then caught all thrown exceptions at 
the point of display. This has the disadvantage of not providing a lot of rich debugging information 
(particularly since several different code paths can throw a "No database connection" exception) but 
has the advantage that we can tell the user something reasonable and fairly cosmetic, while giving 
the developer a hint. 



Summary 

The Certainty Quiz is a small, simple, self-contained PHP application that you should be able to 
install and enjoy in the privacy of your own home (after connecting it to your favorite web server 
and a MySQL database, of course). Although small, the code relies on database interaction, OOP 
features, use of sessions, string processing, object serialization, exception handling, and nontrivial 
arithmetic to achieve its effects. Although PHP has many capabilities that we didn't come close to 
touching on, this chapter uses a fair cross-section of its most popular features — if you understand 
everything in this example, you are well on your way to exploiting the power of PHP. 
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In this chapter's case study, we show one way to use PHP to combine 
MySQL databases with graphic images. We build a complete system 
that starts with a database and uses the gd library to produce a kind of 
visualization of the data. The portions of the book we draw on for this are: 

■ Part II: We use PHP to interrogate a MySQL database. 

■ Chapter 42 (Graphics): Our end product is an image produced 
with the gd library. 

■ Chapter 27 (Mathematics): We need a bit of trigonometry as we 
create the images. 



IN THIS CHAPTER 



From database to image 
Scaled Venn diagrams 
Planning the display 
Putting it all together 



Scaled Venn diagrams 

The visualization we have in mind is something like the Venn diagram. If 
you've ever been in an academic setting where set intersection was being 
discussed, then you've probably seen these diagrams — they're the circles 
that may or may not have overlapping portions representing intersections. 

We say "something like" the Venn diagram, because scale has no signifi- 
cance in a traditional Venn diagram. If you want to illustrate the fact that 
there are people who use both BeOS and Windows, then you might draw 
two circles of equal size (representing Windows users and BeOS users) that 
happen to have a region of overlap. In our version, which you might call a 
scaled or proportional Venn diagram, the sizes of both circles and intersec- 
tions matter; the Windows/BeOS example would become one large circle 
and one much smaller circle, with an overlap area proportional to the 
number of people in both sets. (To see an example of this kind of diagram, 
please skip ahead to Figure 45-5.) 
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The task 

The job of our code is to start with a database, provide a way to query that database about sets 
and their overlap, and then display the results as a scaled Venn diagram, generated by using the 
gd library. As a sample database, we use the pseudosurvey data set that we used in the "HTML 
Graphics" section of Chapter 42. 

If we're going to offer a way to query the database, then it may as well be via a Web form. So the end- 
to-end view of our task is that we start with a Web form and end up with a picture to display. Let's 
start the design by enumerating the things that need to happen for this to come about. We'll need to: 

1 . Generate (or at least present) the Web form itself. 

2. Receive the submitted form data and transform it into appropriate SQL queries for submis- 
sion to the database. 

3. Receive results from the SQL queries. 

4. Use the SQL results to decide on the locations and sizes of all the elements in our graphic. 

5. Actually generate the graphic and send it back to the user. 



NOTE 



All of the code in this chapter should work with either PHP5 or PHP6, but it assumes that 
your PHP installation has access to the gd image library and is configured to produce 
PNG images. Any version of gd later than 1.8, bundled or unbundled, should be OK. (See Chapter 42 
for details of configuration and installation of gd.) 



Outline of the code 

Our system contains the following code files: 

■ vi sua I i zat i on_f ortn . php: This is essentially a hardcoded form that enables the user 
to choose two different restrictions on the data in our table. The restrictions chosen map 
directly to where clauses loaded from an auxiliary file called q u e ry _c 1 a u s e s . p h p . 

■ d b_v isualization.php: This code handles the form data sent by v i s u a I i z a t i o n_ 

form . php and builds three SQL statements: one with only the first where clause, one 
with the second where clause, and a third with both clauses joined by an and. It collects 
the resulting three counts and displays the numbers in a graphic by calling functions 
loaded from v e n n . p h p . 

■ venn. php: This actually produces the Venn diagram graphic and ships it back to the user. 
Its primary function takes as input the three amounts (the sizes of the two sets and their 
intersection), decides the sizes and locations of corresponding circles, and does all the 
drawing and shading necessary. For the complicated case of sets that actually have an over- 
lapping area, it uses functions loaded from tri g . php to calculate areas. 

■ t r i g . p h p : This code actually calculates the intersection area whenever circles overlap. 



772 



Data Visualization with Venn Diagrams 



45 



We discuss these code files in reverse order, from the bottom up. By the way, although we like this 
example, we don't want to give the impression that you need to do trigonometry to do computer 
graphics in PHP, or even vector graphics in PHP. If you want to understand every bit of this example, 
then you need to go through the trig, but we encourage those who don't care to skip the next section 
("Necessary trigonometry"). The core of the graphics code itself is invenn.php, and that example 
code really is important to understand if you want to do gd-based graphics in PHP. 



Necessary Trigonometry 

Let's get the math out of the way first. Unavoidably, because we're talking about circles and areas, 
we're going to be talking about trigonometry. (As we've said, though, if you're not interested and 
are willing to trust us that we have code to calculate the area of circle intersections, please do skip 
ahead to the section "Planning the display," later in this chapter.) 

The eventual task for our system is to start with three quantities (items in set A, items in set B, and 
items in the intersection) and produce a diagram containing two circles, with areas proportional to 
the set sizes, and positioned so that the area of overlap is proportional to the size of the intersection. 
For this section, we go in the other direction and calculate intersection area from given circles. Our 
starting information will be the radii of the two circles and the distance between their centers. 

With reference to Figure 45-1, say that our circles have centers at points C and D, respectively, and 
that we know the radius of the circle on the left (segment CA or segment CB) and the radius of the 
circle on the right (DA or DB). What we'd like to know is the size of that odd lens-shaped object in 
the middle. 



FIGURE 45-1 



Area of intersection 

Area of intersecting circles 
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The lens-shaped intersection area is split into two "halves" by segment AB (not quite halves because 
the circle sizes may be different), and we can calculate the area of each half independently. The cru- 
cial thing to notice is that the area of each of these half-lenses is the area that you get after you sub- 
tract the area of a triangle from the area of a pizza-slice-shaped sector of a circle. The right-hand lens 
half, for example, has an area equal to the sector of the left-hand circle determined by angle ACB, 
minus the area of the triangle ACB. 

So if we can calculate the areas of sectors and triangles, we are nearly done. The area of a sector is 
straightforward — it's just the area of the circle multiplied by the fraction of that circle that the angle 
of the sector sweeps over. 

It takes a little more work and trigonometry to get the areas of the triangles. In our code, we make 
the job more straightforward by drawing a line from point C to point D and considering only the 
half of the diagram above that line — then at the end, we multiply by two to get the real area. If we 
say that the intersection of segments AB and CD is point E, what we eventually care about is the area 
of triangles CAE and DAE. We start by calculating the angles of triangle CDA (whose side lengths 
are known to us) and, by using that information, determining the lengths of CE, DE, and AE. After 
we know these lengths, we know the bases and heights, and the areas of the right triangles CAE and 
DAE are just V2 (base x height). 

Listing 45-1 shows code to do this kind of area calculation. Its main "public" function is circle 
_intersection_area( ), which expects as arguments the radii of two circles and the distance 
between them. The simplest case is where the distance is greater than the sum of the radii: The 
circles do not touch; there is no intersection, and the answer is zero. 



LISTING 45-1 



trig.php 

<?php 

function angl e_gi ven_s i des ($opposite, $other_l, $other_2) { 
if ( ($opposite <= 0) | | 
($other_l <= 0) | j 
($other_2 <= 0) j 

($opposite >= ($other„l + $other„2)) | 
($other„l >= ($opposite + $other_2)) j 
($other_2 >= ($other_l + $opposite))) ( 
die( "Triangle with impossible side lengths in ". 

"angl e_gi ven_sides : $opposite, $other_l, $other_2"); 

1 

el se { 

$numerator = 

((($other_l * $other_l) + 
( $other_2 * $other^2) ) - 
(lopposite * $opposite)); 
$denominator = 2 * $other_l * $other_2; 
return ( acos ( $numerator / Idenomi nator ) ) ; 
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} 

} 

function area_to_radi us ($area! 

return (sqrt ($area / M_PI)); 



function ci rcl e_i ntersecti on_a rea ( $radi us_l eft , 

$radi us_ri ght , 
$di stance) { 

if ( $ r a d i us_ri ght + $radius_left <= $distance) I 
return ( 0 ) ; 

} 

else { 

// first, we find the angle measures of a triangle 
// formed by the two radii and the distance 
// between them 
$1 ef t_sector_angl e = 

angl e_gi ven_si des ( $ radi us__ri ght , $ radi us_l ef t , 
$di stance) ; 
$ ri ght_sector_angl e = 

angl e_gi ven_si des ( $ radi us_l eft, $radius_right, 
$di stance) ; 

// test for obtuseness — the sector angle can 
// be obtuse, but the triangle angle should not 
// be. Also save the result as a sign for the 
// eventual area calculation 

if ($left„sector„angle < M_PI / 2) ( 

$1 ef t_tri angl e_angl e = $1 ef t_sector_angl e ; 
$1 ef t_tri angl e_si gn = 1; 

1 

else ( 

$1 ef t_tri angl e_angl e = M_PI - $1 ef t_sector_angl e ; 
$1 eft_tri angl e_si gn = -1; 

) 

if ( $ri ght_sector_angl e < M_PI / 2) ( 

$ri ght_tri angl e_angl e = $ri ght_sector_angl e ; 
$ri ght_tri angl e_si gn = 1; 

1 

else { 

$ri ght_tri angl e_angl e = M_PI - $ri ght_sector_angl e ; 
$ri ght_tri angl e_si gn = -1; 



// next, find the height of that triangle, assuming 
// the distance is the base 

$hei ght = ($ radi us_l eft / si n ( M_PI__2 ) ) * 
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si n ($1 ef t_t r i angl e_angl e ) ; 
$base_left = ( $radi us_l eft / sin(M_PI_2)) * 

sin(M„PI_2 - $1 ef t_tri angl e_angl e ) ; 
$base_right = ( $ radi us_ri ght / si n ( M_P I_2 ) ) * 

sin(M_PI_2 - $ri ght_tri angl e_angl e ) ; 

// finally find triangle and sector areas, and 
// subtract (or add) appropriately to get the 
// intersection area. Multiply by 2 to reflect 
// areas on both sides of the segment connecting 
// the circle centers 

$1 eft_tri angl e_a rea = $base_left * $height / 2; 
$ri ght_tri angl e_area = $base_right * Iheight / 2; 
$1 ef t_sector_a rea = 

($left_sector_angle / (2 * M_PD) * 

(M_PI * $radius_left * $ radi us_l eft ) ; 
$ri ght_sector_area = 

($right_sector_angle / (2 * M_PD) * 

(M_PI * $radi us_ri ght * $radi us_ri ght ) ; 

$i nter sect i on_a rea = 2 * 
( ( $1 eft_sector_area - 

( $1 ef t_tri angl e_si gn * $1 eft_tri angl e_area ) ) + 
( $ri ght_sector_area - 

( $ri ght_tri angl e_si gn * $ri ght_tri angl e_area ) ) ) 

return ($ intersect! on_a rea ) ; 



?> 



Note that all the angle calculations are in radians, rather than degrees. In radians, a right angle is 
pi/2, and a complete revolution around a circle is 2 pi. We tend to use PHP constants for these val- 
ues whenever we can, in particular M_P I (the value of pi), and M_P I_2 (pi/2). 

There's one final wrinkle that we've ignored in our discussion so far but that we had to deal with 
in the code. The problem is that it's possible for either angle ACE or angle ADE (as we call them in 
Figure 45-1) to be obtuse — that is, more than 90 degrees in size. To see this, look at that diagram 
and imagine what happens as you make the circle on the right smaller, and move its center D pro- 
gressively closer to C. At some point D actually moves to the left of segment AB. In this case, the 
circle intersection area to the left of AB is actually the sum of a sector and a triangle rather than a 
difference. The sector determined by DA and DB sweeps out more than half of the circle centered 
at D, and the remaining portion we want to include is the area of the triangle ADB. We handle this 
in the code by testing if the angles are obtuse and multiplying the triangle areas by either 1 or -1, 
depending on the result of the test. 
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Now we pop up a couple of levels and think about actually generating a diagram. We assume that 
we have as input three numbers (size of set 1, size of set 2, and size of intersection), along with 
some textual labels. We want to scale and locate these circles so that everything has the right 
area, labels are associated with the right circles, and everything fits within the size of the diagram 
we're creating. 

Simplifying assumptions 

We start off with some totally arbitrary decisions that, after being made, simplify everything. We 
decree that: 

■ All the images that we generate are the same size, and that size is 300 pixels high and 600 
pixels wide. 

■ The centers of the circles are always on the same horizontal line. This means that their 
y-coordinate is decided in advance, and we change the area of intersection just by changing 
the x-coordinates. 

■ The circles always fit within the top two-thirds of the diagram (reserving the lower third 
for labels). So put the y-coordinate of the centers one-third of the way down the image 
from the top. And because the circles may not intersect at all, they shouldn't be larger than 
half of the width of the image, so we have room to display two of them. We also make sure 
that the circles are no greater than 90 percent of the room available given everything we've 
said so far, so that they don't touch the image borders. Finally, we decide that, regardless 
of the actual numbers as input, the larger of the two circles is as large as it can be. (Scale is 
consistent within the diagram, but not between diagrams.) 

Determining size and scale 

Now we have nearly all the information needed to create a visualization, and the pieces we are lack- 
ing, of course, depend on the input values we are going to receive. We use the sizes of the actual sets 
to determine the radii of the circles for display. We want the larger of the two set counts to corre- 
spond to the largest circle we can afford to display, and then scale everything else appropriately. (We 
do all this in the code in Listing 45-2 [venn . php] — you may want to look ahead to that code as we 
lay out what we need to do in it.) 

It's actually easiest for us to calculate the largest radius we can afford: Given the constraints we've 
already listed, the larger radius should be 90 percent of l k of the image width, or 90 percent of l h of 
the image height, whichever is smaller. So we calculate this maximum radius, assume that the larger 
set size is proportional to the area of a circle with this radius, and come up with a general conversion 
for mapping from input numbers to area as measured in pixels. We use this to decide on the areas of 
the circles and of the intersection area we want. 
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What numbers should we know at this point? We know: 

■ The radius of the bigger circle. (It's the largest radius that fits our constraints.) 

■ The area of the bigger circle (calculated as nr 2 ). 

■ The radius of the smaller circle (from the ratio of the input set sizes treated as area ratios 
and then mapped back to a radius). 

■ The area of the smaller circle (calculated). 

■ The area of intersection (scaled the same way as other areas, from the input numbers). 

■ The y-coordinate of the circle centers. (We decreed that it be the line that's one-third of the 
way down the image.) 

What are we missing before we can display our circles? The only thing that we're missing is the 
x-coordinates of the centers. 

The easy cases 

Where we decide to put the circle centers depends on the extent to which our sets overlap. There are 
some cases that we can dispense with, that don't need all this trigonometry we've been spending our 
time on. Those are: 

■ No items are in the intersection: In this case, we don't want the circles to touch at all. We 
simply locate the centers at default locations in the middles of the two halves of the dia- 
gram. Because of the way that we limited the maximum radius, the circles are completely 
separated. 

■ One set is completely contained in the other — that is, one of the sets has the same 
size as the intersection: For this case, we just choose to put the center of the larger circle 
in the middle of the diagram and the middle of the other circle offset a bit from it but not 
so much that any of the smaller circle is outside the larger one. 

■ The two sets are the same (and all three input numbers are the same): For this, we just 
draw one circle with an x-coordinate right in the middle of the picture. 

The hard case 

Now the hard one: If the sets only partially overlap, where should we put the circle centers? At this 
point, we have some math in our pocket from the "Necessary trigonometry" section: Given two cir- 
cles and the distance between their centers, we can figure out the area of overlap. Unfortunately, this 
is not the direction we need the calculation go in — we start with the desired area of intersection, 
and we must work backwards to the desired locations of the circle centers. 

Now if we were good and diligent mathematicians but lazy programmers, we would just invert the 
trigonometric equations we used in t r i g . p h p , to solve for center distance rather than for intersec- 
tion area. As it is, though, we're enthusiastic programmers, and if we're any kind of mathematicians 
at all we're definitely the lazy kind. So what we're going to do instead is search for the answer. The 
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function f i nd_ci rcl e_centers ( ) in Listing 45-2 implements a binary search for the answer: It 
starts with a middling distance, asks our trigonometry code what the resulting area would be, and 
successively refines the distance to zero in on the desired area. (The rest of the code in Listing 45-2 
is discussed in the next section.) 



LISTING 45-2 



venn.php 

<?php 

i n c 1 u d e_o n c e ( " t r i g . p h p " ) ; 

$IMAGE_WIDTH = 600; 

$ I MAG E_H EIGHT = 300; 

$ C ENTE R_F I N D I N G_I T E RAT IONS = 20; 

function imagecircle ($image, $center_x, $centen_y, 
$radius, $color) 

{ 

$diameter = $radius * 2; 
imagearc( $image , $center„x, $centen_y, 
$diameter, Idiameter, 0, 360, 
$col or) ; 

} 

function venn_vi sual i zati on 
( $1 ef t_amount , $1 ef t_name , 
$ ri ght_amount , $right_name, 
$ intersect! on_amount ) 

{ 

global $ I MAG E_H EIGHT , $ IMAGE_WI DTH , 

$ C ENT E R_F I NDI NG_ITERATI0NS ; 
// — create the image and allocate colors 
$image = i magecreate ( $ IMAGEJII DTH , $ I MAGE_H EIGHT) 

or die("Could not create image"); 
$background_col or = ImageCol orAl 1 oca te ( $i mage , 255,255,255 ); 
$left_color = ImageColorAllocate($image, 100, 100, 200); 
$ri ght_col or = ImageCol orAl 1 ocate( lirnage , 200, 100, 100); 
$i ntersecti on_col or = 

ImageColorAllocate($image, 225, 225, 225); 
$black_color = ImageCol orAl 1 ocate ($ i mage , 0,0,0); 

// — decide how big the circles should be 
$max_radius = mi n ( ( ( $ I MAG E_H EIGHT * 0.9) / 3), 

( ( $ IMAGE_WI DTH * 0.9) / 4) ) ; 
$center_y = $ I MAG E_H EIGHT / 3.0; 
$default_center_x_left = $ I M AG E_W I DTH / 4.0; 
$default_center_x_right = (3 * $ I MAG E_W I DTH ) / 4.0; 
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$middle_x = $ I MAG E„W I DTH / 2.0; 
$radi us_l ef t_si de_raw = 

area_to_radi us ( $1 ef t_a mount ) ; 
$radi us_ri ght_si de_raw = 

a rea_to_radi us ( $ ri ght_amount ) ; 
$i ntersecti on_radi us_raw = 

a rea_to_radi us ($i ntersecti on_amount ) ; 
$scal e_f actor = $max_radius / 

(max( $ radi us_l ef t_s i de_raw , 

$ radi us_ri ght_s i de_raw) ) ; 
$radi us_l eft_si de = $radi us_l eft_si de_raw * $scal e_f actor ; 
$radi us_ri ght_si de = $radi us_ri ght_s i de_raw * $scal e__f actor ; 
// (it's convenient to pretend that the intersection area 
// has a radius (although it's not circular) just so we can 
// calculate things the same way as the circles) 
$i ntersecti on_radi us = 

$i ntersecti on_radi us_raw * $sca 1 e_f actor ; 
$area_l eft_side = M_PI * 

$ radi us_l ef t_s i de * $ radi us_l ef t_s i de ; 
$area_right_side = M_PI * 

$ radi us_ri ght_s i de * $radi us_ri ght_si de ; 
$i ntersecti on_area = M_PI * 

$i ntersecti on_radi us * $i ntersecti on_radi us ; 

// We now have all necessary info except where to locate the 
// centers of the circles. 

// Four cases: 

// 1) no intersection, 2) partial intersection 

// 3) left is strict subset of right, 

// 4) right is subset of left. 

if ($ i ntersecti on_amount ==0) ( 
// No intersection 

$center_x_l ef t = $def aul t_center_x_l ef t ; 
$center_x_ri ght = $def aul t_center_x_ri ght ; 
$left_fill_x = $center_x_l eft ; 
$ri ght_f i 1 l_x = $center_x_ri ght ; 
$i ntersecti on_fi 1 l_x = -1; 

} 

else if (( $i ntersecti on_area < $area_l eft_side) && 
( $i ntersecti on_area < $a rea_ri ght_s i de ) ) ( 

// The complicated case — we must decide where the 

// circle centers should be so that the overlap is 

// proportional to the set intersection 

// First, we call a function that decides how far apart 

// the circle centers need to be. 

$center_di stance = 

f i nd__center_di sta nee ($ radi us_l ef t_s i de , 
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$radi us_ri ght_si de , 
$intersecti on_area , 
$CENTER_FINDING_ITERATIONS) ; 

// Once we know the distance, we place the circle centers 
// approximately in the middle of the image 
$center_x_l ef t = $middle_x // left/right middle of image 
- ( $center_di stance * 
( $ radi us_l ef t_s i de / 
( $radi us_l eft_si de + 
$ radi us_ri ght_s i de ) ) ) ; 
$center„x__ri ght = $middle_x // left/right middle of image 
+ ( $center_di stance * 
( $radi us_ri ght_s i de / 
( $radi us_l eft_si de + 
$ radi us_ri ght_s i de ) ) ) ; 

// we have decided the sizes and centers of the circles. 
// Now, we must determine good points to start a 
// "flood fill" coloring of the three different regions 
$left_fill_x = 

( ( $center_x_l ef t - $radi us_l eft_side) + 
( $center_x_ri ght - $ radi us_ri ght_si de ) ) 
/ 2.0; 

$ r i g h t_f 111 x = 

( ( $center_x_l ef t + $radi us_l eft_side) + 
($ cent er_x_ri ght + $ radi us_ri ght_si de ) ) 
/ 2.0; 
$i ntersecti on_f i 1 l_x = 

( ( $center_x_ri ght - $ radi us_r i ght_si de ) + 
( $center_x_l ef t + $ radi us_l ef t_s i de ) ) 
/ 2.0; 

} 

else if (($ i ntersecti on_a rea == $a rea_l ef t_si de ) && 
($ i ntersecti on_a rea < $a rea_ri ght_si de ) ) ( 
// The right set completely contains the left set 
// We need to place the left circle somewhere 
// inside the right circle. 
$center_x_ri ght = $middle_x; 
$center_x_l ef t = $middle_x - 

( $radi us_ri ght_si de - $radi us_l eft_side) / 2; 
$left_fill_x = -1; 

$ r i g h t_f ill x = 

( ( $center_x_l ef t + $radi us_l eft_side) + 
($ cent er_x_ri ght + $ radi us_ri ght_si de ) ) 
/ 2.0; 

$i ntersecti on_fi 1 l_x = $center_x_l ef t ; 

} 

else if ( $i ntersecti on_area == $a rea_ri ght_si de ) { 
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$center_x_l ef t = $mi ddl e_x ; 
$center_x_ri ght = $middle_x + 

( $ radi us_l ef t_s i de - $ r a d i us_ri ght_si de) / 2; 
$ri ght_f i 1 l_x = -1 ; 
$1 ef t_f i 1 1 _x = 

( ( $center_x_l ef t - $ radi us_l ef t_s i de ) + 
( $center_x_ri ght - $ radi us_ri ght_s i de ) ) 
/ 2.0; 

$i ntersecti on_f i 1 l_x = $center„x_ri ght ; 



) 



// row, actually draw ard fill regions 

i mageci rcl e ( $ i mage , $center_x_l ef t , $center_y, 

$ radi us_l ef t_si de , $bl ack_col or ) ; 
i mageci rcl e ($ i mage , $center_x_ri ght , $center_y, 

$ radi us_ri ght_s i de , $bl ack_col or ) ; 
if ($left_fill_x > 0) { 

i magef i 1 1 ( $ i mage , $1 ef t_f i 1 l_x, 

$center_y, $1 ef t_col or ) ; 

1 

if ($right_fill_x > 0) ( 

imagef i 1 1 ( limage , $ri ght_f i 1 l_x , 

$center_y, $ ri ght_col or ) ; 

} 

if ( $i ntersecti on_fi 1 l_x > 0 ) ( 

imagef ill ($ image, $i ntersecti on_f i 1 1 _x , 

$center„y , $ i ntersecti on_col or ) ; 

1 

$1 eft_hand„text = "$left_name ( $1 ef t_amount ) " ; 

$ri ght_hand_text = "$right_name ( $ r i ght_amount ) " ; 

$i ntersecti on_text = "Intersection: $i ntersecti on_amount" 

1 ef t_l abel ( $ i mage , $1 ef t_hand_text , $1 ef t_col or ) ; 

ri ght_l abel ( $ i mage , $ri ght_hand_text , $ ri ght_col or ) ; 

i ntersecti on_l abel ($ i mage , $i ntersecti on_text , $black_col 



// send off the image 
header(" Content- type: image/png") ; 
imagepng($image) ; 
imagedestroy($image) ; 



function 1 ef t_l abel ($image, $1 abel_stri rg , $color) ( 
global $ IMAGE_WI DTH , $ I MAGE_H EIGHT; 
i magest r i ng ( $ i mage , 5, 

( $ IMAGE_WI DTH / 4.0 - 

( i magef ontwi dth ( 5 ) * strl en ( $1 abel_stri ng ) ) 
/ 2), 

$ I MAG E_H EIGHT - 55.0, 
$1 abel„stri ng , $color); 
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function right_label ($image, $1 abel_stri ng , $color) { 
global $ IMAGE_WI DTH , $ I MAG E_H E I GHT ; 
imagestni ng ( $i mage , 5, 

( $ IMAGE_WI DTH * 3 / 4.0 - 

( i magef ontwi dth ( 5 ) * st rl en ( $1 abel _stri ng ) ) 
/ 2), 

$ I MAG E_H EIGHT - 55.0, 
$label_string, $color); 



function i ntersecti on_l abel (Simage, $1 abel _st ri ng , $color) { 
global $ I MAG E_W I DTH , $ I MAG E__H EIGHT; 
imagestni ng ( $i mage , 2, 

( $ IMAGE_WI DTH / 2.0 - 

( i magef ontwi dth ( 2 ) * st nl en ( $1 abel _st ni ng ) ) 
/ 2), 

$IMAGE_HEIGHT - 30.0, 
$label_string, $colon); 



function fi nd_center_di stance ($rl, $n2, $desi red_anea , 

$ iterations) { 
// The greatest possible distance is rl + r 2 , and 
// the smallest is abstrl - r2) Let's start in the middle. 
$di stance _guess = (($rl + $r2) + absdrl - $r2)) / 2.0; 
$distance_increment = (($rl + $r2) - absdrl - $r2)) / 4.0; 
for ($x = 0; $x < liberations; $x++) ( 
$cal cul ated_area = 

ci rcl e_i ntersecti on_a rea ($ rl , $r2, $di stance_guess ) ; 
if ( $cal cul ated_anea < $desi red_area ) { 
// move centers closer 
$di stance_guess -= $di stance_i ncrement ; 
$di stance_i ncrement *= 0.5; 

} 

else if ( leal cul ated„area > Ides i red_a rea ) ( 
// move centers apart 
$di stance_guess += $di stance_i ncrement ; 
$di stance_i ncrement *= 0.5; 

) 

else ( 

// unlikely, but ya never know 
brea k ; 

) 

} 

return ($di stance_guess ) ; 

} 

?> 
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Display 

Now we know exactly where we want to put our circles, and how large they should be. What 
remains is the graphics code to actually make the display happen. This is also in Listing 45-2 
(venn . php). 

To produce the graphic, we go through the following steps by using the gd library (which is covered 
in 42): 

1. We create an image by using ImageCreate( ). (At this point, the image is not any particu- 
lar image format, such as PNG or JPEG, but just an internal gd image.) 

2. We allocate colors within the image by using ImageCol orAl 1 ocate ( ) . We care about 
five colors: the background color (white), a color for borders and regular text (black), a 
color for the interior of the left-hand circle (which we decide is bluish), a color for the inte- 
rior of the right-hand circle (reddish), and a color for the intersection (gray). All these col- 
ors are specified by using a red-green-blue scale of 0 to 255. 

3 . We draw the circles in black by using a function of our own, imagecircle(),that takes 
as arguments the image, the radius, the location of the centers, and a color. (See the "Notes 
on circles" section about drawing circles in gd.) 

4. Now, we want to fill in the three areas (the intersection and the two non-intersection por- 
tions of the circles) with the appropriate colors. We use ImageFi 1 1 ( ) for this, which 
flood-fills outward from a specified point until the fill encounters previously drawn lines. 
Choosing the starting points for the fills is somewhat tricky because it depends on the dif- 
ferent intersection cases. In general, though, we start with a y-coordinate that is the same 
as the circle centers and calculate an x-coordinate that's right in the middle of the area we 
are trying to color. 

5. We use ImageStri ng( ) to draw the appropriate labels for each circle, centering each one 
in the middle of the lower third of the image and in the middle of the appropriate left or 
right half. We also create and display a count label for the intersection and display it in the 
middle of the image. 

6. Now, we have a complete gd image, and what remains is to ship it off to the user. We 
send an HTTP header advising the browser that a PNG image is on the way. Then we use 
IrtiagePng( ) to convert the gd image to PNG and send it off. 

7. Finally, we call ImageDestroy ( ) to free any resources associated with the temporary 
image we created. More recent versions of PHP should be handling this already, assuming 
that the image is of type resource, but either way calling ImageDestroy ( ) does no harm. 

Notes on circles 

One thing that puzzles people sometimes, if confronted with the gd functions, is that there seems 
to be no way to draw a circle (or at least there is no function name with c i r c 1 e in its name). This 
is because there are at least two functions that generalize circle-drawing: imageellipse() (avail- 
able only with gd 2.0.1 and later) and i ma gear c. The former draws an ellipse (which can be a circle 
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if the width and height are the same), and the latter draws a circular arc portion (which can be a 
circle if you specify a full 360 degrees of arc). In our code, we chose the latter because we wanted to 
remain compatible with earlier versions of g d . 

Notes on centering text 

As we wrote textual labels in the image code, we actually didn't bother centering the text around any 
horizontal axis, but we did do some left-right centering. We simply used a built-in numbered font 
from g d , calculated the width of our text as displayed by that font (by using imagefontwidth( )) 
and ensured that the left-hand starting point for the text was our desired center minus half the 
width of the text. This was easy, in part because the built-in fonts we used were monospace, and so 
i magef ontwi dth ( ) was able to calculate width by referring only to the length of the string. Things 
get slightly more complicated if you're using a variable-width font — any calculation of string width 
then needs to know the actual string that is printed, not just the number of characters in it. 



Visualizing a Database 



We can now produce these Venn-like diagrams on demand, given some numbers and text to start 
with. Our final task is to hook this up appropriately to a database via a Web form. 

j J r ^j™^~" [ *' 1 ' S a PP" ca *' on ' we assume exactly the same sample MySQL table (programmers) 
^ ■ as we used in Chapter 42. See Listing 42-1 for a description of the data. 

The goal is to let the user choose exactly two restrictions on our database's table, extract counts cor- 
responding to how many rows survive each restriction, count how many rows survive both restric- 
tions, and then pass the results off to our diagramming code. 

Listing 45-3 shows code for a form designed around our particular database, mostly just hardcoded 
HTML. It loads an auxiliary file called query_cl auses . php (shown in Listing 45-4), which is 
extremely hardcoded. This file lists and numbers all the restrictions that we want to offer to users, in 
the form of both an SQL where clause and in an English translation. 



LISTING 45-3 



visualization_form.php 

<HTMLXHEADXTITLE>DB Visual i zati on</TITLEX/HEAD> 
<B0DY> 

<ES>Choose one from each column, and we'll<B> 
display the intersection from the survey data:<BR> 
<F0RM METH0D=P0ST ACTION="db_vi sual i zati on . php" 

TARGET=_new > 
<TABLE> 
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<?php 

i ncl ude( "query_cl auses.php") ; 

for ($x = 0; $x < count( $QUERY_CLAUSES) ; $x++) 1 
print("<TRXTDXINPUT 

TYPE=RADI0 NAME=\"left_clause\" 
VALUE=$x>" . 

$QUERY_DESCRIPTION[$x] ."</TD> 
<TDXINPUT 

TYPE=RADI0 NAME=\"right_cl ause\" 
VALUE=$x>" . 

$QUERY_DESCRIPTION[$x] . "</TDX/TR>" ) ; 

} 

?> 

</TABLE> 

< INPUT TYPE=HIDDEN NAME="table" VALUE="programmers"> 

<INPUT TYPE=SUBMIT NAME=SUBMIT> 

</F0RM> 

</B0DY> 
</HTML> 



Notice that this form is not self-submitting. For this example, we've chosen to completely separate 
PHP-generated HTML pages from PHP-generated PNG pages and avoid the complexity of embedding 
images in HTML. We've also chosen a _new target type for the form submission so that the image 
appears in a new browser window. 



LISTING 45-4 



query_clauses.php 

<?php 

$QUERY_CLAUSES = array( ) ; 
$QUERY_DESCRI PTION = arrayO; 

$QUERY_CLAUSES[0] = "sex = 'F'"; 
$QUERY_DESCRIPTION[0] = "Female"; 

$QUERY_CLAUSES[1] = "sex = ' M ' " ; 
$QUERY_DESCRIPTI0N[1] = "Male"; 

$QUERY_CLAUSES[2] = "language = 'PHP'"; 
$QUERY_DESCRIPTI0N[2] = "likes PHP"; 
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$QUERY_CLAUSES[3] = "language = 'Java'"; 
$QUERY_DESCRI PTION [3] = "likes Java"; 

$QUERY_CLAUSES[4] = "language = 'Lisp'"; 
$QUERY_DESCRI PTION [4] = "likes Lisp"; 

$QUERY„CLAUSES[5] = "language = ' C "' ; 
$QUERY_DESCRIPTI0N[5] = "likes C"; 

$QUERY_CLAUSES[6] = "language = 'Perl'"; 
$QUERY_DESCRIPTI0N[6] = "likes Perl"; 

$QUERY_CLAUSES[7] = "os = 'Linux'"; 
$QUERY_DESCRI PTION [7] = "uses Linux"; 

$QUERY„CLAUSES[8] = "os = 'Solaris'"; 
$QUERY_DESCRI PTION [8] = "uses Solaris"; 

$QUERY_CLAUSES[9] = "os = 'MacOS'"; 
$QUERY_DESCRIPTI0N[9] = "uses MacOS"; 

$QUERY_CLAUSES[10] = "os = 'Windows'"; 
$QUERY_DESCRI PTION [10] = "uses Windows"; 

$QUERY„CLAUSES[11] = "age < 20"; 

$QUERY_DESCRI PTION [11] = "is less than 20 years old"; 

$QUERY_CLAUSES[12] = "age > 30"; 

$QUERY„DESCRI PTION [12] = "is over 30 years old"; 

$QUERY_CLAUSES[13] = "continent = 'North America'"; 
$QUERY_DESCRI PTION [13] = "lives in North America"; 

$QUERY_CLAUSES[14] = "continent = 'South America'"; 
$QUERY_DESCRI PTION [14] = "lives in South America"; 

$QUERY_CLAUSES[15] = "continent = 'Antarctica'"; 
$QUERY_DESCRI PTION [15] = "lives in Antarctica"; 

$QUERY_CLAUSES[16] = "continent = 'Asia'"; 
$QUERY„DESCRI PTION [16] = "lives in Asia"; 

$QUERY_CLAUSES[17] = "continent = 'Europe'"; 
$QUERYJESCRIPTI0N[17] = "lives in Europe"; 
?> 



A screenshot of the form itself is shown in Figure 45-2. 
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FIGURE 45-2 



DB visualization Web form 



00 Visualization - Mozillo {Build 10: 20 02051 COS} 



Pile Edit View Go Bookmarks Tools Window Help D_ebug QA 

O 0} O I v htl P '' !m ■ 1M - 1 ' 1 ' 8 ' J P"' B ~1 I^Saaich | fH] 



Choose on? from each column, and we'll display the intersection from the survey data: 



C? Female 
<~Ma!e 
C tike s PHP 
C [ikes Java 
*~ tikes Ltsp 
r&kesC 

likes Peri 
f uses Linux 
C uses Solaris 
** uses Mac OS 
C uses Windows 
*" is less lhan 20 years old 
P is over 30 years old 
r lives m North America 
C Eves in South America 
C lives in Antarctica 
f lives in Asia 

Eves, i n Emrop.fr 



DociiEneni: Done (1,1 sen) 



C Female 
©Male 
C likes PHP 
f" like s Java 
C likes Lisp 
r likes C 
C Ekes Peri 
C uses Linux 
C uses Solans 
C uses MaeQS 
C uses Windows 

is less than 20 years old 
C is over 30 years old 
C Eves m North America 
(" Eves in South America 
^ Eves in Antarctica 
<~ Eves in Asia 



- j»- | 



One last code file and we're done. We have our image creation code and a form for requesting an 
image. The last piece of the puzzle is code to handle the form submission, perform the appropriate 
counts on the database, and call the image code. This code is shown in Listing 45-5. 



LISTING 45-5 



db_visualization.php 

<?php 

i ncl ude_once( "dbconnect.php"); 

i ncl ude_once( "query_cl auses.php"); 

i n c 1 u d e_o n c e ( " v e n n . p h p " ) ; 

if UsSet($_P0ST['table']) && 

IsSet($_P0ST['left_clause']) && 

IsSet($_P0ST[ ' right_cl a use' ] ) ) ( 
Stable = $_P0ST[ 'table' ] ; 
$1 eft_cl ause_id = $_P0ST[ ' 1 eft_cl ause ' ] ; 
$ri ght_cl ause_i d = $_P0ST[ ' ri ght_cl ause ' ] ; 

$left_clause = $QUERY_CLAUSES[$1 eft_cl ause_id] ; 
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$right_clause = $ QU E RY_C LAU S E S [ $ r i ght_cl ause_i d] ; 

vi sual i ze_i ntersecti on (Stable, $1 ef t_cl ause , 

$ r i ght_cl ause ) ; 

} 

else ( 

print("Form submission not handled cornectl y . <BR> " . 
"Did you choose all options?"); 

} 



function vi sual i ze_i ntersecti on (Stable, $1 ef t_cl ause , 

$ ri ght_cl ause ) 



$left_query = "select count(*) from Stable 

where $1 eft_cl ause" ; 
$right_query = "select count (*) from Stable 

where $ri ght_cl ause" ; 
$i ntersecti on_query = 

"select count(*) from Stable 

where $left_clause and $ri ght_cl ause' 

$result = mysql_query ( $1 ef t_query ) 

or die("Query was $1 ef t_query : " . mysql_error( ) ) ; 
$row = mysql_fetch_row($resul t) ; 
$left_count = $row[0]; 



$ result = mysql_query ( $ ri ght^query ) 

or die(mysql_error()); 
$row = mysql„f etch_row( Sresul t ) ; 
$right_count = $row[0]; 



Sresult = mysql_query ($ i ntersecti on_query ) 

or die(mysql_error()); 
$row = mysql_f etch_row( Sresul t ) ; 
$i ntersecti on_count = $row[0]; 



venn_vi sual ization($l ef t_count , $1 ef t_cl ause , 

$ri ght_count , $ ri ght_cl a use , 
$i ntersecti on_count ) ; 

) 

?> 



The submission form passes in index numbers of SQL clauses, rather than the clauses themselves, so 
we don't need to worry about escape characters in the submission. The form-handling code includes 
the same que ry_c lauses.php file, so the index numbers should always agree. The form handler 
collects the two clauses, creates three SQL statements out of them, executes the statements to get 
counts, and uses the results as arguments to the venn„vi sual i zati on ( ) function. 
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Note that Listing 45-5 refers to one auxiliary code file we haven't mentioned yet: dbconnect . php. 
We assume that this file contains (or refers to a file containing) your MySQL username and pass- 
word, and also makes a call to mysql ^connect ( ) to create a global DB connection for the rest of 
the script. Something like the following should suffice: 

<?php 

$user = 'USER' ; 
$pass = ' PASS' ; 
$db = ' venn ' ; 

mysql_connect('localhost', $user, $pass) 

or di e ( " Coul dn ' t make DB connection:" . mysql_error( ) ) ; 
mysql_select_db($db) ; 
?> 

This assumes that your username and password are replaced appropriately, and that you have a MySQL 
database called venn, which contains a table called programmers, as described in Chapter 42. 

Trying it out 

Now that our system is complete, let's give it a spin. Bringing up v i s u a 1 i z a t i o n_f o r m . p h p , we 
choose the first option from the left-hand column (Female), and the second option from the right- 
hand column (Male), and submit. The result is shown in Figure 45-3 — two separate circles because, 
given the database schema, it's impossible for anyone to be both male and female. (Please, no e-mails 
about the narrowness of our views — it's just an example!) 



FIGURE 45-3 



No intersection 



1 dt> visualizaliou.php (PNG Image, 600x300 pixels) - Moiilla [Build ID: 2002051006] 


■ -lOlxl 


„ File Edi I View go Bookmarks Tools Window Help Debug (JA 


Q Q Q Q I nsnnaEHEiEiE iK\s..ichi 


sex = T" (11) sex = *M" (20) 




Intersection: t> 




Document: Done (0.72 sees) 


-J.- bP 
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On a color monitor the left-hand circle is bluish, while the right-hand circle is reddish. Because this 
is a grayscale book, though, you probably see two gray or black circles. 

Now a different query: uses Sol a ri s on the left, and 1 i ves in Anta rcti ca on the right. (We 
chose this deliberately, knowing that our lone South Pole correspondent sees only one kind of Sun 
during the winter.) 

The result is shown in Figure 45-4: one small gray circle inside a larger blue one, indicating that all 
Antarcticans are Solaris users but not vice versa. 



FIGURE 45-4 



Subset 



db visuiilizdlion.php (PNG Image, 690x300 pixels) - Moiilli! (Dtiild ID; 2002051006} 



^ File Ed r i View (Jo Bo a kmar ks T o o Is Win d o w H e I p Debug Q A 




os = 'Solaris* (8) continent = 'Antarctica' (1) 

Iriter-section: 31 



Finally, for the more typical case, let's choose 1 i kes PHP from the left, and uses Li nux from 
the right. 



The result, in Figure 45-5, is two mostly overlapping circles. (Again, please no letters — we have no 
idea if these proportions match the world as it is or just the world as we would like it to be.) 
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FIGURE 45-5 



Partial intersection 



db_visualifdlicn.php (PNG Image, 900x3(10 pixels) Mozilla {Build ID: 2002051006] 



F i I c £ di I View Go Bo o kmar ks Tools Win d o w He I p Debug Q A 



J j Q \j i 'v iaumkaii>»»^»^ | i^s a «ch i <S> C 



l-lnlxl 




lanauage = 'PHP' (12) os = 'Urux' (17) 

Intersection; 3 



DncBimem: Done $.77 sorafl 



Extensions 

This example works nicely, but as always, there are countless ways in which it could be tweaked, 
improved, and especially extended. Naturally, there is a lot you could do to change the cosmetics of 
the images or to make the look more configurable. 

The weakest part right now in our view is the form submission, which is hardcoded to pertain only 
to a particular known MySQL table. Much cooler would be code that, armed only with a table (or 
view) name and the appropriate login, would quiz the database about column names and types and 
the distribution of values, and then develop such a form on its own. 

One extension that may immediately occur to you doesn't work, unfortunately, at least without sub- 
stantial changes to the display code. There is no good way to involve a third set (and circle) in the 
diagram, cover all the cases, and be assured that all the shapes can still be circular. If you have any 
doubt about this, try diagramming the following three sets: people who were born in Europe, people 
who currently live in Europe, and people who currently live in a continent different from the one 
they were born in. 
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45 



Summary 

We've shown you a small but complete system for visualizing data in a MySQL database. It allows 
the user to select aspects to compare, makes corresponding SQL queries, and transforms the results 
into a scaled Venn diagram, showing how the database records overlap. 

In addition to using MySQL techniques from Part II of this book, we drew on the image techniques 
from Chapter 42, and as little math as we could get away with from Chapter 27. 
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In this appendix, we assume that you have more C (or C++) program- 
ming experience than PHP experience and are looking to get up to 
speed in PHP quickly. First, we'll provide a quick overview of PHP 
from a C perspective; next, we'll break down the similarities and differ- 
ences, and finally we'll point out which parts of the book you are likely to 
benefit from the most. 

The simplest way to think of PHP is as interpreted C that you can embed in 
HTML documents. The language itself is a lot like C, except with untyped 
variables, a whole lot of web-specific libraries built in, and everything 
hooked up directly to your favorite web server. The syntax of statements 
and function definitions should be familiar, except that variables are always 
preceded by $, and functions do not require separate prototypes. 



Similarities 



In this section, we offer some notes (by no means exhaustive) on ways in 
which PHP can be expected to be C-like. 



Syntax 



Broadly speaking, PHP syntax is the same as in C: Code is blank-insensitive, 
statements are terminated with semicolons, function calls have the same 
structure (my_f uncti on(expressionl, express i on2 )), and curly 
braces (( and ) ) make statements into blocks. PHP supports C and C++ style 
comments (/* */ as well as / /), and also Perl and shell-script-style (#) ones. 
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Operators 

The assignment operators (=,+=,*=, and so on), the Boolean operators (&&, | , !), the comparison 
operators (<, >, <=, >=, ==, ! =), and the basic arithmetic operators (+, -,*,/, %) all behave in PHP 
as they do in C. 

Control structures 

The basic control structures (if, swi tch, whi 1 e, for) behave as they do in C, including support- 
ing break and conti nue. One notable difference is that swi tch in PHP can accept strings as case 
identifiers. 

Many function names 

As you peruse the documentation, you'll see many function names that seem identical to C functions. 
It's a safe bet that these functions perform the exact same tasks, although they may sometimes take a 
slightly different form in terms of arguments or the way results are returned. Most string-modifying 
functions, for example, return new strings as the value of the function rather than modifying a string 
passed as an argument. Note, however, that function names are not case-sensitive in PHP. 



Differences 

Although PHP has quite a bit of C ancestry, it also has some other ancestors (Perl, shell scripts), as 
well as some unique features not at all C-like. 

Those dollar signs 

All variables are denoted with a leading $ . Variables do not need to be declared in advance of assign- 
ment, and they have no intrinsic type — the only type a variable has is the type of the last value 
assigned to it. The PHP version of the C code: 

double my_number; 
my_n umber = 3.14159; 

would simply be: 

$my_n umber = 3.14159; 

Types 

PHP has only two numerical types: integer (corresponding to a long in C) and double (corresponding 
to a double in C). 
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Strings are of arbitrary length. There is no separate character type. (Functions that might take char- 
acter arguments in their C analogues typically expect a one-character string in PHP ( ord ( ) , for 
example.) Beginning with PHP4, there is also a genuine Boolean type (TRUE or FALSE). See the fol- 
lowing sections for arrays and objects. 

Type conversion 

Types are not checked at compile time, and type errors do not typically occur at runtime either. 
Instead, variables and values are automatically converted across types as needed. This is somewhat 
analogous to the way arithmetic expressions in C will "promote" numerical arguments as needed, 
but it is extended to the other types as well. (See Chapter 25 for details of the conversion rules.) 

Arrays 

Arrays have a syntax superficially similar to C's array syntax, but they are implemented completely 
differently. They are actually associative arrays or hashes (with some additional supporting 
machinery), and the "index" can be either a number or a string. They do not need to be declared or 
allocated in advance. 

No structure type 

There is no struct in PHP, partly because the array and object types together make it unnecessary. 
The elements of a PHP array need not be of a consistent type. 

Objects 

PHP4 had a very basic OOP syntax, which allowed definition of classes with member data items and 
member functions. PHP5 introduces a much fuller object model, although in approach and syntax it 
owes more to Java than to C++. Some highlights: abstract classes, private/protected members, con- 
structors/destructors, and interfaces (but no multiple inheritance as in C++). 

No pointers 

There are no pointers per se in PHP, although the typeless variables play a similar role. PHP does 
support variable references. You can also emulate function pointers to some extent, in that function 
names can be stored in variables and called by using the variable rather than a literal name. 

No prototypes 

Functions do not need to be declared before their implementation is defined, as long as the function 
definition can be found somewhere in the current code file or included files. 
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Memory management 

The PHP engine is effectively a garbage-collected environment (reference-counted), and in small 
scripts there is no need to do any deallocation. You should freely allocate new structures — such as 
new strings and object instances — especially because they will reliably go away when your script 
terminates. If you need to free memory within a script's execution, call u n s e t ( ) on the variable that 
refers to it, which will release the memory for collection. External resources (such as database result 
sets) can also be explicitly freed within a script, but doing so is worth it only if the script would use 
an unacceptable amount of the resource before terminating. 

In PHP5, it is possible to define destructors for objects, but there is no free or delete. Destructors 
are called when the last reference to an object goes away, before the memory is reclaimed. 

Compilation and linking 

There is no separate compilation step for PHP scripts — the development cycle is simply edit-reload. 
Errors and warnings show up in the browser output by default, although there is also an error- 
logging capability. Typically, there is no dynamic loading of libraries (although such a capability 
exists) — you decide at PHP configuration time which function families to include in your module, 
and they are then available to any script. 

Permissiveness 

As a general matter, PHP is more forgiving than C (especially in its type system) and so will let you 
get away with new kinds of mistakes. Unexpected results are more common than errors. In par- 
ticular, under the default error-reporting level, PHP does not warn you if you use a variable that has 
not yet been assigned (although it does supply reasonable default values rather than garbage). If you 
would rather be warned, you can set the error-reporting level by evaluating error_reporting(E_ 
ALL) early in your script, or set the error-reporting level to E_A L L permanently by editing the php . 
i ni file. 



Guide to the Book 

In writing this book, we very intentionally did not assume that the reader had prior knowledge of C. 
Because PHP resembles C in many aspects, some of the chapters may cover familiar ground. This is 
especially true of Part I, which is essentially a language introduction. 

In Table A-l, we label the chapters of Part I according to how familiar they are likely to be to C pro- 
grammers. Parts III, IV, and V are more PHP-specific and likely to be novel, but you may also find 
portions of Part II to be familiar if you have some experience with SQL databases. 



798 



PHP for C Programmers 



TABLE A-1 



Guide to Part I for C Programmers 


Chapter 


Chapter Title 


Verdict? 


Notes 


1 


Why PHP? 


Novel 


The chapter you need to justify PHP to 
your boss. 


2 


Server-Side Scripting 
Overview 


Novel 


Important if you have not seen web- 
scripting languages before. 


3 


Getting Started with 
PHP 


Novel 


Installation, hosting, and so on. 


4 


Learning PHP Syntax 
and Variables 


Mostly familiar 


Skimmable until the section on variables 
(which really are different in PHP). 


5 


Learning PHP Control 
and Functions 


Mostly familiar 


All the PHP control structures (i f, whi 1 e, 
swi tch, for) work the same way as in 
C. Some differences in function behavior, 
particularly with scoping of variables. 


6 


Passing Information 
with PHP 


Novel 


Specific to web-scripting. 


7 


Learning PHP String 
Handling 


Mostly familiar 


Doubly quoted strings do automatic 
interpolation of variable values. 


8 


Learning Arrays 


Novel 


Deceptively familiar — PHP arrays are 
syntactically like C arrays but behave 
totally differently. 


9 


Learning PHP Number 
Handling 


Familiar 


Two numerical types, corresponding to the 
long and double types. Numerical operators 
are as in C. 


10 


PHP Cotchas 


Novel 


Error messages and stumbling blocks do not 
have much overlap with C. 



A Bonus: Just Look at the Code! 

As a final bonus, C programmers are uniquely qualified to benefit from the open source nature of 
PHP. Although the combination of this book and the online manual should answer almost all your 
questions, if you have the PHP source available you may be able to gain some extra insight by pok- 
ing around in it and seeing how things are implemented. Although you would need to be familiar 
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with lexing/parsing technology to get much out of the parser code itself, many PHP functions are 
simple wrappers around their similarly named C counterparts, and some others that have no C 
counterparts are at least implemented in clear and simple C. 

It's also easy for C programmers to add new capabilities to the language, whether for their own use 
or for eventual use by the PHP community. Most PHP programming tasks are addressed by writing 
PHP (often by defining functions in PHP), but you can also pop the hood and add functionality to 
the underlying language by adding a new module, written (of course) in C. 
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In this appendix, we assume that you know Perl, but not PHP, and are 
looking to quickly get up to speed in PHP. The good news is that the 
two languages are very similar indeed. 

This is by no means a comprehensive guide to how Perl and PHP compare. 
Although similar, and sharing some ancestry, they really are distinct lan- 
guages with distinct syntaxes and feature sets, and there is no replacement 
for getting to know them individually. Our main goal for this appendix is 
to save you some time up front — to warn you, for example, that el s i f 
means nothing in PHP (but that el sei f , however, is significant) rather 
than letting you debug your way to that realization. 



Similarities 

In this section, we discuss some ways in which PHP and Perl are similar. 

Compiled scripting languages 

First, the obvious: Both Perl and PHP are scripting languages. This means 
that (unlike compiled languages such as C) they are not used to produce 
native standalone executables in advance of execution, which can then be 
run without reference to the language they were written in. Instead, Perl or 
PHP source files are both fed to an appropriate engine at execution time. 
This does not mean, however, that Perl/PHP code is interpreted line by line 
at execution time; in both Perl and PHP, scripts are quickly and automati- 
cally compiled at execution time and then executed. But it does mean that 
the development cycle for PHP/Perl programmers is edit-execute, rather 
than edit-compile-execute, as in C. 
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Syntax 

PHP's basic syntax is very close to Perl's, and both share a lot of syntactic features in common with 
C. Code is insensitive to whitespace, statements are terminated by semicolons, and curly braces 
organize multiple statements into a single block. Function calls start with the name of the function, 
followed by the actual arguments enclosed in parentheses and separated by commas. 

Dollar-sign variables 

All variables in PHP look like scalar variables in Perl: a name with a dollar sign ($) in front of it. (See 
the "Differences" section for what happened to @ and %.) 

No declaration of variables 

As in Perl, you don't need to declare the type of a PHP variable before using it. The following line is 
legal in both languages, with no prior mention of the variable called $the_answer: 

$the_answer = 42; 

Loose typing of variables 

As in Perl, variables in PHP have no intrinsic type other than the value they currently hold. This is 
different from languages such as C and Java, in which once a variable is declared to be for holding, 
say, strings, you get into trouble if you try to use it to store an integer. 

The following sequence of two lines is legal in both Perl and PHP: 

$the_answer = 42; 
$the_answer = "the answer"; 

The variable $the„answer is assigned sequentially to an integer and a string. This would not be 
legal in more strongly typed languages such as C, Pascal, or Java. 

Strings and variable interpolation 

Both PHP and Perl do more interpretation of double-quoted strings ("string") than of single- 
quoted strings ('string'). In particular, the value of $ variables is spliced into double-quoted 
strings at the time the strings are read. 

The following code fragment is both legal Perl and legal PHP, and it has the same behavior in both 
languages. 

$the_answer = 42; 

$the_statement = "the answer is $the_answer" ; 
At the end of the second line, the variable $the_statement contains the string: 
the answer is 42 
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Differences 

This section warns you (again, not exhaustively) about some ways that Perl and PHP diverge from 
each other. 

PHP is HTML-embedded 

Although it is possible to use PHP for arbitrary tasks by running it from the command line, it is 
more typically connected to a web server and used for producing web pages. The code for these 
pages can consist partially (or even completely!) of straight HTML, with fragments of PHP embedded 
in them to produce the dynamically generated portions. 

If you are used to writing CGI scripts in Perl, the main difference in PHP is that you no longer need 
to explicitly print large blocks of static HTML using print or heredoc statements and instead can 
simply write the HTML itself (outside of the PHP code block). Also, for typical pages, there is no 
need to explicitly send HTTP headers from PHP code. 

No @ or % variables 

PHP has one only kind of variable, which starts with a dollar sign ($). Any of the datatypes in the 
language can be stored in such variables, whether scalar or compound. For example, the expression 
$ my _a r r a y [ 0 ] refers to the first element in an array, while $my_array refers to the array itself. 

Arrays versus hashes 

PHP has a single datatype called an array that plays the role of both hashes and arrays/lists in Perl. 
For all the details, see Chapter 9; the short version is that a PHP array acts like a Perl hash when you 
supply keys and like a Perl (nonassociative) array when keys are omitted. Values can be extracted by 
key (as in Perl hashes) or by iteration through the array (as with Perl arrays). 

There is, however, a 1 i s t ( ) function in PHP. It's used to extract the contents of an array into a set of 
separate variables. The 1 i st ( ) function works like this: 

SmyArray = ('a', ' b ' , ' c ' ) ; 
list($varl, $var2, $var3) = SmyArray 

After that runs, $varl contains a, $var2 contains b, and $var3 contains c. 

Specifying arguments to functions 

Function calls in PHP look pretty much like subroutine calls in Perl. Function definitions in PHP, on 
the other hand, typically require some kind of list of formal arguments as in C or Java. For example, 
although the typical syntax for a two-argument subroutine in Perl might look like: 

sub two_arg_sub ( ) ( 

my ($first_arg, $second_a rg ) = @_; 
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) 

The corresponding PHP function definition would be: 

function two_arg_f uncti on ($first_arg, $second_arg ) ( 

} 

Although your humble authors try hard not to be partisan, we feel strongly that subroutine argu- 
ments in Perl are a bug and that function arguments in PHP are a feature. Two kinds of silliness 
common in Perl that don't usually arise in PHP are: (1) popping the argument stack at various points 
in a subroutine (so that it is hard for a reader of the code to figure out what the formal arguments 
are supposed to be) and (2) compound arguments bleeding into one another because arguments are 
passed as a list of scalars. PHP arguments arrive intact and without confusion regardless of number 
and type. 

Variable scoping in functions 

In Perl, the default scope for variables is global. This means that top-level variables are visible inside 
subroutines. Often, this leads to promiscuous use of globals across functions. 

In PHP, the scope of variables within function definitions is local by default. This means that (with 
some exceptions) the only variables visible within functions are the formal parameters and variables 
assigned locally within the function. If you want to refer to a variable from the global context within 
a function, you must declare it by name in the function definition itself, using the global keyword. 

The exceptions to that rule in PHP are the so-called superglobals, the most popular of which is $_ 
POST. Representing the variables that arrived at a PHP script as a result of an HTTP POST operation, 
$_P0ST and its contents are accessible anywhere, without the need to use the gl oba 1 keyword. 

For example, if we called a PHP script with this URL: 

http://localhost/quoteStooges. php?stoogel=Curly&stooge2=Shemp 

these calls would be legal anywhere in: quoteStooges.php: 

lookupQuote( $_GET[ 'stoogel']); 
1 ookupQuote($_GET[ 1 stooge2 ' ] ) ; 

No module system as such 

In PHP there is no real distinction between normal code files and code files used as imported 
libraries. To import a PHP code file full of function or class definitions, simply use i n c 1 u d e ( ) , 
requi re( ), or requi re_once ( ) , which have much the same effect as splicing the definitions in at 
the point of the statement. 
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Break and continue rather than next and last 

Perl has some idiosyncratic language keywords, which are not the same as the corresponding C con- 
structs. In general, if Perl and C disagree about such a name, you will find that PHP follows C rather 
than Perl. In particular, if you want to skip to the end of a for or whi 1 e iteration, use continue 
(not next); if you want to break out of the loop altogether, use break (not 1 ast). 

No elsif 

A minor spelling difference: Perl's el s i f is PHP's el seif . Also, its use is not mandatory. In PHP, 
the following is legal: 

if ( $bool ean_va r ) { 

# case 1 

1 

else if ( $other_bool ean ) ( 
# case 2 

1 

In Perl, on the other hand, if you for some reason decline to use elsif, your other alternative is the 
more awkward form: 

if ( $bool ean_va r ) { 

# case 1 

1 

else ( 

if ( $other_bool ean ) I 
# case 2 

I 

1 

More kinds of comments 

Perl people like the phrase "There's more than one way to do it," and yet they suffer with a really 
impoverished set of options for comments. In addition to Perl-style (#) single-line comments, PHP 
offers C-style multiline comments (/* comment */ ) and Java-style single-line comments (/ / 
comment). 

Regular expressions 

PHP does not have a built-in syntax specific to regular expressions, but has most of the same func- 
tionality in its "Perl-compatible" regular expression functions. See Chapter 22 for the details. 



Miscellaneous Tips 

Following are answers to a couple of questions that Perl programmers might have on their minds. 
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What about use of strict "vars"? 

Like Perl, PHP allows you to use variables without declaring them or initializing them, and (as 
in Perl) this capability is a frequent source of bugs. If you would like a declaration like Perl's use 
strict "vars", try error_report i ng ( E_ALL ) , which will at least warn you about the use of any 
unassigned variables. 



Where's CPAN? 

PHP doesn't yet have a code repository as comprehensive as the Comprehensive Perl Archive 
Network (CPAN), but the PEAR project provides a reasonable substitute (http : / /pear . php . ret). 



Guide to the Book 

As in Appendix A (PHP for C Programmers), in this section we offer Perl hackers a quick guide to 
Part I of the book to give a sense of which chapters are likely to already be familiar. 



TABLE B-1 



Guide to Part I for Perl Programmers 


Chapter 


Chapter Title 


Verdict? 


Notes 


1 


Why PHP? 


Novel 


The chapter you need to justify PHP to your 
boss 


2 


Server-Side Web 
Scripting 


Possibly novel 


Familiar to Perl CGI and mod_perl 
programmers; important if you have not seen 
web scripting before 


3 


Getting Started 
with PHP 


Novel 


Installation, hosting, and so on 


4 


Learning PHP 
Syntax and 
Variables 


Novel but easy 


"Hello world" for PHP 


5 


Learning PHP 
Control and 
Functions 


Somewhat familiar 


Basic constructs are similar, with syntactic 
differences 


6 


Passing Information 
with PHP 


Mostly familiar 


Specific to web scripting 


7 


Learning PHP 
String Handling 


Somewhat familiar 


Treatment of single-quoted and double- 
quoted strings essentially the same; functions 



are mostly novel 
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Chapter 


Chapter Title 


Verdict? 


Notes 


8 


Learning Arrays 


Novel 


No exactly corresponding data type in Perl 


9 


Learning PHP 
Number Handling 


Mostly familiar 


Novel section on arbitrary-precision (BC) 
math functions. 


10 


PHP Gotchas 


Novel 


Same gotchas around unintentionally 
unassigned variables; other gotchas specific 
to PHP parsing 
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This appendix contains specific advice for HTML-only jocks looking 
to trade up to something a little more powerful on the server side. If 
you already know ASP, JavaScript, or almost any real programming 
language, this appendix is not going to help you much. 



The Good News 

If you're already proficient at HTML, starting to use PHP is not a huge step. 
Because PHP is usually embedded in HTML, extending the functionality 
of static web pages with a programming language can be a very natural 
progression. There are plenty of reasons to believe that you can learn PHP 
fairly quickly, such as the following factors. 

You already know HTML 

Because PHP is often embedded in HTML, and because PHP generally uses 
HTML for display to the browser, you won't be able to see anything that 
your scripts are doing unless you output HTML. In fact, you can think 
of PHP as simply adding functionality to web pages — it can do other 
things, but lots of people use it mostly for form handling and dynamic page 
generation. 

You presumably have a lot of practice debugging HTML, which is all to the 
good. Many errors occur within the HTML parts of scripts or during the 
transitions between modes, so the ability to read and write HTML with 
great facility is crucial. 
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If you're strong on the design side, as are many HTML coders, you have the ability to produce a 
good-looking and well-laid-out product. This skill is important for the community because a lot of 
early PHP developers were not exactly known for their UI skills (including ourselves, we hasten to 
admit). So go out there and show the world that PHP sites doht need to be ugly, clunky, or, at best, 
really plain — you can make us all proud. 

PHP is an easy first programming language to learn 

Unlike many major programming languages, PHP enables you to do useful stuff from the very 
beginning instead of making you play endless games of tic-tac-toe or code up incomprehensible 
math problems. The web browser and markup languages, however primitive and clunky they are 
now, point the way to the universal I/O, windowing, and multimedia solution that the world has 
been waiting for. PHP takes full advantage of the web's power; plus it has very little overhead and 
takes a loose, inclusive approach to issues such as types, variables, and syntax. All the nitpicky angst 
that programmers used to put into these areas you can now apply more directly to functionality. 

And frankly, PHP enables you to learn just those parts that are useful to you and ignore the rest. 
Unlike some programming languages, which pretty much require a firm grasp of all the basic prin- 
ciples before you can do anything useful (try telling a C programmer that you just haven't seen a 
need for structs yet if you want a laugh), no one is going to give you a quiz on all the hundreds of 
PHP functions before entrusting you with a text editor. So if you don't need to write some huge math 
function right off the bat, go ahead and skip that chapter — we promise not to tell. If you ever need 
them, the math capabilities will still be there. 

Web development is increasingly prefab anyway 

Finally, the web is increasingly making development a matter of altering prefab open source code 
rather than hacking it all up yourself. Much of this work is about changing how the page looks 
rather than how it functions. Learn to be a smart script shopper, and you're more than halfway 
there. 



The Bad News 



Before we get too carried away, honesty compels us to admit that you may face a few hurdles before 
you become a power PHP user. 

If programming were that easy, you'd already 
know how 

PHP is a real programming language, similar to C (albeit generally web server dwelling), rather than 
a tag-based markup concept such as HTML or ColdFusion. This point introduces whole new levels 
of complexity. It simply takes time and practice to develop a bag of tricks, work out routines for solv- 
ing problems, and just get better at development — and there are no shortcuts for these skills. 
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So here's the bottom line: Most of PHP is probably completely new to you. Unlike new PHP develop- 
ers who are already proficient with ASP, JavaScript, or C, you can't expect to pick up any specific 
points here that are highly similar to things you already know how to do. Uh, sorry. 

However, if you already know some JavaScript or have taken an "Intro to C" class in school — even 
if you wouldn't describe yourself as a JavaScript or C guru — you're ahead of the curve. Some of the 
logic is sure to come back to you as you begin to work with PHP. 

Backend servers can add complexity 

PHP is mostly useful in conjunction with backend servers, such as database and mail servers, which 
have their own syntax and implementation issues that you need to learn about. Because open source 
software such as PHP is commonly used in noncorporate settings, most PHP developers probably 
don't have the luxury of a team of database, network, and design experts doing their various things 
while they just worry about the middle and front tiers. 

If possible, don't try to learn everything at once. The most important task is to become comfortable 
with the web server itself; Apache, in particular, is an extremely powerful but involved piece of soft- 
ware that rewards study. (This advice may not be relevant if you have IT staff to install and maintain 
the web server for you.) After that, you will almost certainly want to learn SQL if you don't know it 
already. Mail service is also a very rewarding subject. After you master those three, other new serv- 
ers should be easier to learn. 



Concentrate On . . . 

Learning PHP quickly requires a strategy. Here are some things you might want to concentrate on 
doing when you're first learning. 

Reading other people's code 

Learning to read other people's code can be harder than it sounds. One of the best things about PHP 
is its loose syntax and inclusive "don't worry, be happy" design — but that can also mean that differ- 
ent scripts can look very different, even if they return similar results. Beginners can be boggled by 
stylistic issues and may find it difficult to sort out which parts of a script are functionally irreducible 
and which are the products of one individual's programming quirks. But regardless of difficulty, the 
sooner you can parse other people's PHP and the more code you can look at, the better off you'll be. 

One potentially helpful exercise is to visit the mailing-list archive or a code exchange (see Appendix 
D) and print out multiple examples of code that solve the same issue (preferably one you're inter- 
ested in). Then lay the sheets side by side, take a big ol' red pen and go through it all, circling the 
common parts. Give extra brownie points to any scripters who comment their code well (which 
doesn't necessarily mean the most voluminous comments but rather the most useful) and look for 
more code from those people. Also look for code that is generally well laid out and logically orga- 
nized, even if it isn't extensively commented. 
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Working on what interests you 

We firmly believe that learning is motivation. If you find tasks that you want to accomplish, you will 
automatically be motivated to learn what you need to know to accomplish them. Don't let anyone tell 
you that the right way to learn programming is through some highly structured program of math 
problems, games, and stock-market simulations. Wanting to put pictures of your dog on the Internet 
is much more important than making sure that you know what's in every byte of memory your pro- 
gram is using. 

Thinking about programming 

As we said earlier, learning PHP is inevitably going to take time, practice, and lots of example code. 
There is just no way around it, and there is not a whole lot more to say on the subject. 

One thing that may prove helpful to new developers, particularly those of a narrative rather than 
mathematical bent, is the judicious use of pseudocode. For example, you might start out with mostly 
pseudocode and gradually add real PHP as we do in the steps that follow: 

1 . Write down the tasks that you want this page to accomplish. Being complete is more 
important at this stage than being cogent. Following is an example of a script mission 
statement: 

This page should display a form with any old answers already filled in. 
Then you can submit the form to update some of the values if you want 
to. And I want the form to be password-protected, so it needs to handle 
a User ID passed in from the login screen. 

2. Break the mission statement down into steps and substeps, as in a recipe. Rearrange these 
if necessary. Following is an example of this step: 

1. Get the User ID that is passed from the login screen; if none, 
don't display anything. 

2. Display the HTML form. 

3. Make any old values from the database appear in the form. 

a. Connect to the database server. 

b. Download data about this item. 

c. Put the data into the HTML form's "value=X" variables. 

4. Change the values and put them into the database too. 

5. Pass the User ID to the next page. 

3. Pick one of the steps and turn it into actual PHP code. Starting with a core PHP task — such 
as sending e-mail or returning something to the screen — is generally easier than beginning 
with peripheral tasks, such as connecting to a database. Any time you might want to connect 
to a database, use a commented variable, array, or include file for the moment. The following 
example illustrates this step: 

1. Get the User ID that is passed from the login screen; if none, 
don't display anything. 
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<?php 

// Dummy UserlD pretending to be passed from login. 
// Will be superseded later. 
$UserID = 1; 
?> 

2. Display the HTML form. 

<HTMLXHEADX/HEAD> 

<B0DY> 

<F0RM> 

First name: <input type="text" size=30 name=" Fi rstName"XBR> 
Last name: <input type="text" size=30 name=" LastName"XBR> 
E-mail: <input type="text" size=30 name=" Emai 1 "> 

3. Make any old values from the database appear in the form. 
<?php 

// I'm using these variables now, but later I'll get 
// them from the database instead. 

$Fi rstName = "Joyce" ; 
$LastName = "Park" ; 
$Email = "root@l ocal host" 

?> 

Oh, I think I need to put them in before the form is rendered. 

4. Change the values and put them into the database, too. 

5. Pass the User ID to the next page. 

4. Gradually fill in more and more of the code, fixing any new issues that arise. You may want 
to keep some of the pseudocode, suitably edited, as comments, as shown in the following 
example: 

/* Pass the User ID to the next page. The best way is to have it 
show up as a hidden input type and PHP variable in the form; 
then HTML can pass it with the rest of the POST values. */ 

Learning SQL and other protocols 

Spending some time interacting with backend servers directly, via whatever interface the server pro- 
vides, is generally a good idea before you add the complexity of PHP between you and the server. 

You can kill two birds with one stone by using the backend server's own interface to construct 
the database (or whatever), even though there may be nice PHP tools for some of these tasks. For 
instance, even though the phpMyAdmi n and MySQL Control Center are both very slick and handy 
ways to deal with the MySQL database, the newbie database administrator can learn a heck of a lot 
more by using MySQL's deliberately primitive command-line interface. 
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Beginning with PHP5, a lightweight, embedded database engine called SQLite is included and ready 
for you to use. SQLite is rudimentary and not up to the task of replacing MySQL and other database 
engines on a production site; however, you may find it an excellent tool for getting your feet wet 
before moving on to MySQL. 

Making cosmetic changes to prefab PHP applications 

One common way to ease into using PHP is to enlist your frontend web development skills to cus- 
tomize a preexisting PHP package. 

■ First try just changing the colors — that's generally pretty safe. If that goes well, try cus- 
tomizing the buttons. The next safest thing is spacing — table widths, columns, and so 
on. You can also add graphics, add links, or play around with style sheets pretty much 
without worries. 

■ If the application has include files (especially header, inc), the cosmetic part is often 
in there. Look first in headers and footers for colors, the basis of page layouts, and so on. 
Remember to match header changes with corresponding footer changes and vice versa. 

■ Never, ever erase a line beginning with a conjunction (such as i f , wh i 1 e, or for). If 
you are not 100 percent sure of what you're doing, comment out code blocks rather than 
deleting them. 

Debugging is programming 

Few people truly enjoy debugging; as one of our colleagues once observed, "I'd rather implement 
new features than eat someone else's leftovers." Debugging can turn out to be a useful learning 
experience, however, because you can fix things at the edges of a big project instead of jumping into 
writing the whole thing from scratch. 

One of the most efficient ways to debug is in pairs. If you're tired or have seen a piece of code too 
many times, focusing on every detail can prove difficult. At this point, talking through your logic 
becomes very helpful — one of you briefly stating why you're doing what you're doing and the other 
checking each step off very deliberately. A fresh set of eyes can often find cheap mistakes such as 
misspelled variable names or missing brackets more quickly, too. If you get an opportunity to debug 
with a more experienced programmer, take it. 



Avoid at First . . . 

A few things in PHP are extremely unfamiliar to HTML coders and generally are not extremely 
necessary to writing functional PHP. Try to avoid the elements that we describe in the following sec- 
tions if you can, at least at first. 
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Maximal PHP style 

See Chapter 32 on PHP style. The maximal style is deprecated by Rasmus Lerdorf himself, and only 
hardcore C programmers have the slightest excuse to use it, except in very specific, brief instances. 
It includes too many single quotation marks, double quotation marks, forward slashes, backslashes, 
ASCII line breaks, and HTML line breaks for most coders. Beginners are better off if they don't waste 
their time worrying about stray punctuation when they could be spending the time and effort grasp- 
ing larger concepts instead. 

Programming large applications from scratch 

Why reinvent the wheel? In Open-Source-Land, you don't need to. Becoming a good customizer and 
recycler of other people's code is often more efficient than trying to become the world's greatest pro- 
grammer from scratch. Learn to shop for what you need. 



Consider This . . . 

The ideas in the following sections are completely optional but may prove helpful. You may not 
agree with them all, but we offer them for what they're worth. 

Reading a book on C programming 

Unfortunately, we can't write a complete programming tutorial. Part I of this book explains pro- 
gramming topics but necessarily very briefly. We've tried to comment our code samples extensively, 
but we can do only so much to explain these techniques in passing. 

Mailing-list regulars frequently counsel new PHP developers to buy a book on C programming — but 
in a snotty, RTFM way that too often elicits a naturally passive-aggressive response. Nevertheless, 
if you separate the suggestion from the unspoken message that you must be a clueless idiot, it's 
good advice and something to seriously consider if you're having trouble with the programming 
aspect of PHP. 

A clearly written, brief tutorial book is Patrick Henry Winston's On to C (Addison-Wesley, 1994). It's 
fewer than 300 pages, and a lot of the PHP-relevant material is right at the beginning. The standard 
reference is The C Programming Language by Brian W. Kernighan and Dennis M. Ritchie (Prentice 
Hall, 1988), which is quite definitive but more reference-oriented and, therefore, perhaps less appro- 
priate for HTML-only coders. A friendlier introduction might be Dan Gookin's two-volume C For 
Dummies (Wiley, 1997), which has cartoons and dry humor. 

Minimal PHP style 

Of the range of PHP styles, the easiest for the HTML coder to work with at first is the most minimal. 
In other words, we suggest that you separate the HTML and PHP sections completely. Not only does 
this technique avoid many stylistic difficulties, but by using this method, you avoid mixing PHP and 
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HTML glitches on the same page, which makes diagnosing problems more than twice as hard. We 
discuss this topic thoroughly in Chapter 32. 

Perhaps the easiest way to use the minimal style is to finish the HTML pages first, using whatever 
tool you're most enamored of. Take the time to debug your HTML completely and perhaps run it 
through a tidying utility. Then, and only then, tackle the PHP parts, secure and comfy in the knowl- 
edge that any difficulties you encounter are certainly on the PHP side rather than the HTML side. 

One downside of this style is that you can't have pages pass their variables back to themselves. This 
is particularly relevant with forms, so if your site has a lot of forms, you may want to change your 
style a bit as your PHP skills improve. 



Use the right tools for the job 

Finally, you want to consider using a PHP-enabled text editor for the PHP parts of your scripts. 
(See Chapter 3 for a discussion of text editors versus WYSIWYG tools.) Some people can do won- 
ders with just Notepad or ema c s , but a lot of frustrated beginners are certainly using those tools 
just because someone told them that's what the cool programmers do. As Zsa Zsa Gabor said (in a 
slightly different context), macho does not mean mucho. If you work more effectively with v i m or 
Visual SlickEdit, by all means use those tools. 

Syntax highlighting (printing different parts of the code in different colors) can help you a lot, as it 
will usually make clearer when you have failed to insert a closing parenthesis or double quotation 
mark. Some programmer's text editors will automatically line up your curly braces for you, which 
helps you verify that you've closed off all of a set of nested cases. We would not even consider using 
a text editor without line numbering, since PHP's built-in error messages always refer to lines in 
your code. And last but not least, do not forget the power of "View Source" in the browser — this 
will help you verify that the output you are producing is in fact what you intended. 

'"- - i f. ' This advice does not apply to WYSIWYG editors, the use of which we deprecate. Sooner 
or later, you need to fix up the HTML into a human-readable form, which no WYSIWYG 
editor can yet produce. If it's your choice to use one, fine — but you should in no way think of this tool 
as a substitute for understanding and writing clean HTML by hand. 
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his appendix lays out some basic resources that can help you learn 
more about the language. We have also tried to mention specific 
resources and products throughout the text. 



The PHP Web Site 



The URL for the PHP web site (engrave it on your forehead) is www. php.net. 
Here you'll find the latest official news, the freshest downloads, the PHP bug- 
tracker, a growing list of PHP users' groups, and links to PHP-friendly ISPs. 

Most important, you'll find the PHP manual in the Documentation section 
of the PHP web site. It's available in several versions for your universal ref- 
erence pleasure, including the following: 

■ Numerous translations — many European languages, Japanese, 
Korean, and so on 

■ Several PDF, Windows Help, and HTML download versions (use- 
ful when you're traveling; HTML versions are included with the 
PHP download) 

■ Two versions for Palm OS 

■ A plain HTML online version 

■ Links to the PHP-GTK (client-side PHP) and PEAR (PHP code- 
base) manuals 

■ Information on beta releases that are not yet ready for production use 

A comprehensive listing of all downloads is available at www .php.net/ 
downl oad-docs . php. 
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Cj'^~^~^ t ^ ne PEAR manual, which used to be a chapter of the general PHP manual, has now been 
moved to its own server. You can find it at http://pear.php. ne t /ma nu. a 1 

But when people talk about "the PHP manual," they mean the big annotated online version for which 
PHP is famous. Users from around the world have added notes and comments to each page. These 
additions are often clarifications of points made in the main text, additional insights, and reports of 
PHP's behavior on various platforms. 



Navigating the PHP Manual 

Our experience suggests that something about the organization of the manual makes it difficult or discour- 
aging for many users to quickly find what they're looking for. To locate information about a function or 
construction, you sort of need to know that it's there and what kind of thing it is (not always clear from the 
headings — for example, date functions versus calendar functions), and often it helps to have an idea of what 
the PHP team might have named it. If you can't accurately guess these three things, you're likely to spend a 
lot of time wandering around looking at not-quite-right function pages. We have nothing comforting to tell 
frustrated users, except that PHP has so many functions and configuration options and styles that writing about 
and organizing them all in a way that makes sense to an outsider is very difficult. Our hope is that books such as 
this one can help introduce you to the main categories (for example, array functions) and the most commonly 
used functions — and then you'll be more prepared to use the riches of the online PHP manual. 

One extremely helpful thing we recommend is reading the introductory page for each section of the online 
PHP manual. The manual is broken up into sections or chapters, such as "Arrays" and "Regexps"; each section 
has a "front page," which can be accessed via the "Function Reference" part of the online manual's table of 
contents. Usually (although not always) this page will have a lightning-quick introduction to the subject of the 
manual chapter, helpful hints, and a list of the functions in that section. By reading through these introductions, 
you will have a much better idea of the various things that PHP can do, and greatly increase your chances of 
being able to put your finger on just the function you need at any given moment. 

The English-language version of the online PHP manual has a cool feature that can save a lot of time for certain 
users, particularly those experienced in another programming language. If you type the name of a function as 
a top-level URI, the official PHP site automatically forwards you to either the page devoted to that function (if 
it exists) or a search page with a completed search for that term (if it doesn't exist or doesn't have a discrete 
page). So, for instance, if you type http : / / www .php.net/popen, you'll be redirected to www .php.net/ 
manual /en/ f uncti on . popen . php. This is the same functionality as typing a search term into the search 
box in the page header. If you're looking for a PHP function that is similar to one in C or Perl, this trick can 
prove a great timesaver over navigating the manual by hand. It's also useful in cases where you know the name 
of the function but just want to check on the type of variable returned or the order of arguments to pass in. 



You may want to keep a couple of points in mind when using this manual: 

■ The canonical manual text is written in a super-terse programmer's style, and it is orga- 
nized in a not particularly discursive, notebook-like format. 
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j ry j p I The online manual is not the place to ask questions! It's intended for meaningful com- 

ments and observations only. Send e-mail to one of the previous commentators who pro- 
vide their addresses — many of them will be happy to help you. Or subscribe to the mailing list or post 
to a PHP forum, which is faster anyway. Remember, a stupid question posted to the manual errata will 
go down on your (semi) permanent record. 

■ The comments are edited, weeded, and verified only on an episodic (not to say extremely 
infrequent) basis. Proceed with extreme caution — there have been numerous instances of 
problems actually getting worse because a user uncritically followed the advice in the man- 
ual notes. You can write to the person to make sure that the advice is appropriate for you or 
even to determine whether the person really knows what he or she is talking about. 

■ The manual may lag behind development by a considerable time period. 



The PHP Mailing Lists 

The "official" PHP community meets and greets on the PHP mailing lists. With the advent of PHP4, 
a decision was made to split up the lists into more specific topics. These topics will continue to pro- 
liferate with the addition of new features. 

Signing up 

To subscribe to any of the PHP mailing lists, go to www .php.net/mailing-lists.php. 

You should see a large form listing the various mailing lists and options for viewing them. Just 
choose the list that you want, specify normal or digest versions, enter your e-mail address, and click 
the Subscribe button. You can also unsubscribe from a list here. 

The PHP mailing list manager almost instantaneously sends you an e-mail message asking you to 
confirm your subscription. You aren't subscribed until you reply to this e-mail. 

j-jjj-., F You also find links to local (non-English) mailing lists and newsgroups at the bottom of this 
eUJ^^^^K page. If you want to discuss PHP in Turkish or Japanese, this page is the place to start! 

Users' lists and developers' lists 

Many of the user-oriented lists are new with PHP4 or later. The following are the most popular PHP 
users' mailing lists: 

■ php.general: Mam mailing list — very heavy traffic, 80+ e-mail messages per day 

■ php.windows: Specific mailing list for Windows users 

■ php.install: An installation-related mailing list, mostly for new users 

■ php.db: The database-related issues mailing list 
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■ php.il8n: Internationalization and localization mailing list 

■ php.pear: The PEAR users' list 

■ php.gtk.general: The PHP-GTK users' list 

■ php.smarty.general: The Smarty templates users' list 

■ php.bugs: Bug reporting related to PHP itself 

■ php. announce: Announces new releases — very occasional 

Lists also are available for popular PHP-based projects such as Midgard and phpNuke; you subscribe 
to those lists through the products' own web sites. We list the URLs of some of these sites in the 
"Major PHP Projects" section later in this appendix. 

The following four lists are mostly intended for active developers and very early adopters — people 
who are going to get down in the C code and battle bugs to the death: 

■ php.dev: The main PHP developers' list 

■ php.gtk.dev: The PHP-GTK developers' list 

■ php.pear.dev: The PEAR developers' list 

These lists are low-to-medium volume, meaning approximately 100 to 1,000 messages a month. 
They are highly technical and mostly not enlightening unless you're an active team member. Various 
CVS lists for developers are also available, which mail out all CVS commits on a particular branch to 
all subscribers; special lists for documentation writers and QA team members also exist. 

If you're comfortable with Internet newsgroups (which many newer users are not), you can access 
the PHP mailing lists through the news gateway at news. php. net. 

This option has one great advantage: You can send messages to the mailing lists without subscribing 
to them. Many new users, however, should think in terms of searching the archives for answers to 
old questions before (or rather than) asking new questions anyway. 

Most of these mailing lists, and many others on a variety of topics, are archived and searchable at 
http: //marc. theaimsgroup. com. 

This archive dates back to at least 1998, although the older posts are usually less complete. 



It's actually faster for you, plus the less time the developers must spend answering the same questions 
over and over, the more time they have to implement new features in the language. Actually, searching 
the archives is no longer just polite — it's a necessity. With so many new users, so-called "RTFM" (read 
the effing manual) questions are not (politely) answered on the PHP lists anymore. Also, try to ask your 
question on a specific list if it exists — especially installation-related questions. 




Trying a quick keyword search on the PHP site, mail archives, and perhaps some of the 
other major PHP web sites before contacting the mailing lists is the polite thing to do. 
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Regular and digest 

The main PHP user list is so high-volume that it has a twice-daily digest version. The new special- 
ized mailing lists also typically have digest versions. The raw and digested versions each have 
advantages and disadvantages. 

If you've never had 100+ e-mail messages a day pouring into your mailbox, you have no idea how 
distracting and time-consuming this experience can be. Just reading-and-deleting can take up a 
couple hours, whereas actually answering them can easily become a full-time job. Under no circum- 
stance should you request the full user list if your primary mailbox is a web-based free e-mail ser- 
vice such as Yahoo! mail or Hotmail. 

pTTj - ^ F Setting up a separate mailbox for PHP mail is almost mandatory if you're subscribing to 
the full user mailing list, unless you've set up good mail filters. Otherwise, you quickly 
start to lose mail from other sources in the flood of similarly named threads. 

On the other hand, the digest version makes getting into the flow more difficult. The few brave com- 
munity members who get the full user list seem to answer all the questions on the half-volley before 
you even get the digest, making participation difficult for the time-stressed community member. 

For beginners, we recommend the digest version. You can always trade up later, whenever you're 
ready to stop lurking and participate actively. 

Everyone should also consider using one of the PHP forums (see the following section on "Other 
PHP Web Sites") instead of or in addition to the user mailing list. These forums are great for those 
who dislike mailing lists. The downside is that PHP developers generally don't hang out here, so 
extremely abstruse infrastructure questions usually go unanswered. The upside is that they tend 
to be friendlier, especially to repetitive newbie questions, because the answerers can control the 
amount of contact they prefer and go away if they start to become annoyed. 

Mailing list etiquette 

Open source mailing lists can be intimidating places, and the PHP general-users list is particularly 
active and fast-paced. The denizens of the mailing lists are people, and learning about their different 
personalities and plans over time can be fun — but they can get annoyed and fed up, too. A little 
netiquette can take the user a long way. The following sections offer a few tips to follow. 

Remember, the community does all this work for free! 

Before you turn on the flamethrower, remind yourself of your last experience with commercial- 
software tech support. Did it solve your problem the same day? Did it cost money? How long did it 
take? At what point did you get to talk to the developers of the program? 

People might be sick of your question 

Perhaps you're trying to install PHP for the first time and can't get it working as an Apache module — 
but we can assure you that tens of thousands of iterations of that question have appeared on the mail- 
ing lists over the years. People on the mailing lists are experiencing fatigue at answering questions that 
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they and others have answered in a lot of other information sources — the FAQs, the online manual, 
the mailing-list archives, and any number of other web sites. If you ask one of these basic questions 
on the general mailing list, it proves that you didn't take seriously the numerous polite requests on 
the PHP site to search for an answer to your question before posting. You may get an irritated e-mail 
informing you of all the above — or you may get no responses at all. Neither response means that the 
PHP community is cold-hearted and unhelpful. Try to see things from the point of view of community 
members of longer standing, and avoid these problems by searching for the answer to your question 
before you post. 



Give detailed descriptions 

Say as much as you can about your platform, the problem, and any steps you've already tried. Don't 
worry about being concise; you're far better off meandering on a little than making everyone go back 
and forth an extra time. 

Code fragments are the very most efficient way to state your problem for debugging by the com- 
munity. Many people edit their raw code to make it more anonymous and/or abstract. Remember to 
take out any passwords! 

r | V) ^- I Copy and paste your code fragments; don't retype them. List participants often post per- 

• feet code, only to be frustrated that nobody can find anything wrong with it — because 
they corrected their errors while retyping! 

Make sure that you use a specific subject line — the more specific the better. "Subject: PHP Help" 
gets you ignored by most of the mailing-list regulars. You want to say something more descriptive 
such as, "Subject: mysql_connect arguments not being passed in 4.0.0." 



PHP is international 

PHP is developed and used by people literally all over the world. In fact, the active development 
team has only a smallish minority of native English speakers on it at any given time. 

Native English speakers should feel supremely lucky that theirs is the lingua franca of the Internet 
in general and the PHP world specifically. They should feel awed by the linguistic dexterity of all the 
citizens of other nations and perhaps slightly abashed that they can't return the favor in Finnish or 
Urdu. In other words, cut people some slack already! Don't assume that someone is an idiot because 
his or her messages aren't couched in perfectly grammatical and smooth English. Instead, you might 
spend the time learning how to write "Thank you" in all the languages of the various PHP commu- 
nity members — it makes a nice sig file for your mailing list posts. 

rTTj™" T If you don't know English well, you may want to write your question twice — once in 

■ English, once in your native language. This will increase the odds that someone will be 
able to decipher your meaning. 

There are limits 

The mailing list and other resources are meant to help you, but you must prepare to make a good- 
faith and even strenuous effort of your own. Help does not mean that someone comes to your office 
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and writes your code — this is not a remake of the Disney version of Cinderella, with dancing, sew- 
ing, chore-doing mice! Please don't ask community members to go into your server and debug your 
scripts for you. 

Every once in a while, someone gets on the mailing list and whines about how PHP doesn't have pre- 
cisely the feature that he or she is looking for — to which the developers very sensibly reply, "Why 
don't you implement it yourself?" Or, if you're not a good C programmer yourself, you could always 
pay someone else to develop your feature and contribute it to the PHP community. At the very least, 
you can avoid doing things that may alienate others or cause developers to burn out on the whole 
idea of developing open-source software! 

Do it yourself 

Open source software may be free to use, but you should not consider it free of all responsibilities. 
You are technically a "free rider" until you give back — or pay forward — to the community at large. 
It's your task to figure out where and how to best deploy your talents, and then to do that thing as 
you can. We don't mean that every casual PHP user must become a C developer, but you can con- 
tribute in many other ways. Answering questions on the PHP mailing lists or web sites is always 
a good thing, because it lightens the load on the core developers. If you figure something out that 
seemed obscure in the online PHP manual, be sure to post your findings to the User-contributed 
notes section of the manual. Use the PHP bug- tracker according to the instructions. Simple steps like 
these, in aggregate, contribute to the healthy community that has made PHP so successful. 

It's probably you 

If you experience a failure to communicate, you need to ask yourself whether the problem could 
possibly lie with you. If you do find yourself in the middle of a flame war, which happens occasion- 
ally on any mailing list, people enjoy nothing more than a little public acknowledgment of what a 
jerk you've (unknowingly) been. 

There are now commercial alternatives 

If the whole ethos of the PHP mailing lists is driving you crazy, remember that you can now pay to 
play instead. Many companies are now staffed by well-known PHP developers who are willing to do 
everything from answering single questions to building a custom PHP extension for you. ThinkPHP 
(www .thinkphp.de), for example, is a German consultancy, associated with PHP team member 
Thies Arntzen, that offers support, training, and performance evaluations. In the United States, the 
supremely helpful Richard Lynch of PHP-mailing-list fame takes requests at www . 1 - i - e . com. 



Other PHP Web Sites 

Besides the official PHP resources that we mention in the preceding sections, some well-known com- 
munity members have put up some extraordinarily helpful web sites. Some of these enjoy a special 
relationship with PHP, and are "quasi-official." The following sections describe some of these sites. 
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Core scripting engine and tools 

The core of PHP is the Zend scripting engine. It is produced by an Israeli company called Zend, and 
besides being a free part of PHP, it can be embedded in other applications. Zend also produces vari- 
ous PHP tools and add-ons, such as a graphical debugger and a precompiler. You can find informa- 
tion on Zend products at www . zend . com. 

Zend.com is the home of the core PHP5 scripting engine, as well as a center of PHP commercializa- 
tion. Although the company sells support and custom development services to larger companies, the 
vast majority of PHP developers are most interested in the add-on products being developer by core 
developers Zeev Suraski and Andi Gutmans and their team. 

For most PHP users, the most useful product is the Zend Studio IDE, now in 3.0.1 release. (See 
Chapters 3 and 32 for more information and screenshots.) This program is the first PHP-specific 
development tool available, with many well-designed features for the PHP professional. Because of 
Zend's unique relationship to PHP development, the company understands the language completely 
and can design an editing tool that is customized to the needs of hardcore PHP users. 

Two other Zend products are primarily of value to companies. PHP consulting firms should find the 
Zend Encoder useful, as it enables them to ship their code in a platform-independent, optimized 
intermediate representation. Large PHP sites can get a quick return on investment by using the Zend 
Accelerator, which boosts performance by optimizing and caching, thereby requiring less capital 
investment in hardware. 

The Zend site also offers unique content on a regular basis, including biographies of major figures 
in the PHP world, a handy weekly newsletter summarizing current issues in the development of 
our beloved programming language, and great articles on advanced topics in PHP development. 
Zend.com is one of the few web sites that consistently offers articles of interest to corporate PHP 
developers and architects, often showcasing the finer points of PHP functionality, such as refer- 
ence counting, output buffering, and changes to the include functions. Topics such as these may 
seem abstruse at first, but advanced users usually enjoy learning about the underlying structure and 
logic of the programming language so that they can write the tightest, cleanest, most secure, best- 
architected, and most well-thought-out PHP code possible. C programmers who want to contribute 
to PHP can also find inspiration and information in these articles — because Zeev and Andi are 
driving the course of PHP core development, getting a feeling for their aesthetic and decision making 
is important if you want to delve into the heart of PHP. 

PHP knowledgebase 

PHP has a great knowledgebase, something like a FAQ-o-matic but more full-featured, called PHP 
Faqts (previously known as E-gineer). It is available at http : / /php . f aqts . com. 

PHP Faqts is an interesting and nicely executed concept: an archived knowledgebase of answered 
and unanswered questions from real PHP users with a decent search function. For common ques- 
tions, this site is much easier to use than the mailing lists or even many forums — and for that rea- 
son, we recommend it to new PHP users. 
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The way that Faqts (brainchild of Australian PHP whiz Nathan Wallace) works is that commu- 
nity members ask questions in one of several "buckets," such as Installation and Setup, Common 
Problems, Database Backed Sites, and the extremely cool Not Quite PHP. Other community mem- 
bers come along and add multiple answers to these questions. They can also associate other ques- 
tions (basically other ways of stating the same thing) with that question/answer pair. Everyone can 
vote anonymously on whether the question/answer was useful or not. Thus, you get an accretion of 
knowledge over time and some way to discern whether a particular answer is good at a glance. 

Going to this site, however, is not the fastest way to get your question answered, and it remains to be 
seen whether Faqts can scale indefinitely — but it's a cool idea and definitely a resource to try. 

Articles and tutorials 

Articles and tutorials take a "teach a man to fish . . ." approach. Often they can't really walk you 
through all the steps involved in building your web site; instead, they attempt to guide you in think- 
ing about what to do. Following are two sites that we recommend for such information. 

■ PHPBuilder (www .phpbuilder.com). Founded by Tim Perdue, the top PHP app developer 
responsible for Sourceforge.net and Geocrawler.com, this site has long been one of the most 
comprehensive and well-run PHP sites. The specialty of the site is a deep backlog of articles 
that focus on the correct architecture of PHP sites, with subjects such as user authentica- 
tion, cross-platform development, database abstraction, and documentation and style. 
PHPBuilder also boasts one of the most active PHP-related web forums, with excellent 
response times to most questions. 

■ One downside to the site is that articles are not dated, so determining whether the advice is 
still relevant to current versions of the programming language can prove difficult. Despite 
this drawback, PHPBuilder is a must-visit for the more conceptual PHP programmer who 
wants to read well-argued position papers on the right way to code PHP. 

■ Devshed (www . devs hed . com/Server_Si de/ PHP and www .devshed. com /Serve r_ 
Si de/ My SQL). A big commercial site with good tutorials and a forum, Devshed covers all 
the scripting languages (ASP, JavaScript, Python, and so on) as well as MySQL, making it 
the best one-stop for those still in the shopping phase. 



PHP codebases 

Codebases take a "give a man a fish . . ." approach, simply offering their donated wares to all takers. 
The code quality can vary widely, from first scripts to elegant classes contributed by experts in a 
particular area. The following sections describe a few such sites that you can visit. 



~ ^" k * Although codebases can seem attractive to new developers and do embody the power 
" - - of open source, there are reasons to be wary. For one thing, no one is guaranteeing the 



quality or safety of this code. If you're more comfortable cutting and pasting than writing it yourself, 
you may not have sufficient skill at reading other people's PHP to use contributed code in an intelligent 
way. Proceed with caution! 
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■ PHP Classes Repository (www .phpclasses.org): Originally a collection ol classes by 
Manuel Lemos, this site is now a hotbed ol OOP PHP. We would probably not recommend 
this site to beginners, both because ol the heavy use ol object-oriented programming and 
the strong leaning toward code in the "Sure you can, but is it a good idea?" category You 
should also possess an understanding ol the changes in the object model from PHP4 to 
PHP5. II you're good at intelligently reading other people's code and adapting it to your 
own needs, however, this site can prove instructive. 

■ PX: PHP Code Exchange (http://px.sklar. com): A super-plain and uninlormative site 
design nonetheless leads to a large variety ol scripts — mostly smaller ones. Look here for a 
standalone snippet or lunction in a specialized area, such as graphics or math. 



I A quick rule of thumb in judging contributed code: If you can't follow along pretty well 
■ just by reading the comments, take a pass and look for another code sample. It's pretty 
rare for a good commenter to be a bad or malicious programmer. 



Major PHP projects 

These are the more ambitious standalone projects based on PHP that are becoming well known in 
their own right. Even organizations that are not necessarily in love with PHP are beginning to con- 
sider these projects as the best-ol-breed and/or most cost-elfective option in their various categories. 

■ PHPMyAdmin (www . phpmyadmi n . net): Originated by Tobias Ratschiller, this program 
is a graphical Irontend to MySQL that has brought database administration to the ranks ol 
the command-line phobic. See Chapter 14 for more detailed information on how to use it. 

■ PHP-Nuke (http://phpnuke.org): This site offers a newslog-style content management 
system that enables multiple users on an intranet or the web to post stories and comments on 
an ongoing basis. You can lind lots ol add-on packages written by enthusiastic users as well. 

■ PHPSlash (http://phpslash.sourceforge.net): This site also offers a newslog-style 
content management system. It was originally a rewrite of Slashcode (the Perl codebase 
behind Slashdot) in PHP, although PHPSlash development has now diverged somewhat. 

■ Midgard (www .midgard-project.org): This site offers a highly customizable content 
management system, similar to Vignette Story Server. Midgard doesn't simply enable users 
or editors to post short pieces in a constant format on a web page; you can also use the pro- 
gram to manage workflow on all kinds ol content-rich sites. 

■ phpBB (www . phpbb . com): This is an object-oriented, template-based bulletin-board sys- 
tem offering threaded or flat view, skins, avatars, and other attractive display features. 

■ Phorum (www . phorum . org): Phorum is a lighter-weight bulletin-board system with 
no graphics. Unlike most other PHP bulletin boards, Phorum displays an outline ol the 
thread, plus the current message, plus a form to reply to that message on a single page. 

■ SquirrelMail (www . squi rrel mai 1 . org): IMAP web mail client. 

■ Serendipity (www . s9y . org): Full-featured blogware, comparable to (commercial and Perl- 
based) Movable Type and Blogger. One of the authors of this book is a team member. 
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■ PHPWiki (http : //phpwi ki . sou rceforge.net): Popular Wiki system. 

■ PHPGroupware (www. phpgroupware . org): This large integrated suite of PHP programs 
offers you web-based group-scheduling and interaction tools, including web mail, a calen- 
dar, to-do lists, chat, forums, and more. 

■ Sourceforge.net (http://sourceforge.net/projects/alexandria-dev): This is a 
web-based engineering management toolkit that includes a task tracker, a bug tracker, a 
CVS frontend, forums, a documentation manager, and news releases. The codebase went 
closed source in 2001. 
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The PHP Extension and Application Repository (PEAR) is a broad 
effort with many component parts, collectively aimed at expanding 
the usefulness and reliability of the PHP language. PEAR has been 
removed from PHP6 but was previously (and likely will continue to be) an 
important part of many developed applications for years to come. For this 
reason, while we didn't include coverage of PEAR in the main section of 
the book we're including it as an appendix in the hope that you'll get some 
value out of the material. 

As of late, there has been discussion about how to get PEAR back into the 
main PHP source, so it may be back between the time we write this and 
the time you read this! That is all the more reason to include some cover- 
age of PEAR. 

Since PEAR isn't included in PHP6, some of the installation steps may no 
longer be applicable to a PHP6 system. You can find the latest installation 
instructions at http : / /pear . php . net. 

With PEAR, developers should be able to write more capable software more 
quickly and with greater reliability. 

The most useful and best-known element of PEAR, its package manage- 
ment system, attempts to reduce the frequency with which PHP developers 
reinvent the wheel. Its main part is an online database of code modules, 
accessible to anyone via an automated process, that give the PHP language 
special capabilities. PEAR modules, for example, enable PHP program- 
mers to access LDAP directories and open files in the Ogg Vorbis format 
without writing utility classes for those jobs. Programmers using the PEAR 
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packages can focus on the functionality of their creations, rather than wasting time struggling with 
nuts-and-bolts problems. 

The PEAR initiative also includes a set of rules about how code is to be written — a style guide, if 
you like. The PEAR coding style rules are meant to govern modules contributed to the PEAR archive 
but in fact apply well to all PHP work. You could do worse than to apply the PEAR coding style rules 
to all your PHP programs. 

PEAR has a sister project, the PHP Extension Community Library (PECL, pronounced pickle). PECL 
modules are extensions to PHP itself, rather than just PHP modules that can be imported into PHP 
programs as needed. Together, PEAR and PECL make PHP much more capable and enable many 
more people to participate in the development of the language. 



What Is PEAR? 

There are many common tasks in PHP that require or strongly benefit from libraries of functions. 
There are many web sites where PHP community members offer code they've written, but how do 
you know the code is good, will be maintained and extended, and doesn't have any odd quirks or 
even malicious features? The PEAR project offers a large and growing library of known-good, well- 
maintained, well-documented PHP code that has passed many quality inspections — all free for the 
taking. 

The PEAR project began in 1999, shortly after PHP itself came into being. It's a community-driven 
initiative dedicated to generating open source code that improves PHP. PEAR packages are built on 
top of the standard PHP functions, and are often written in an object-oriented style (for example, 
classes). You include these modules from your own PHP script with anincludeO orrequire() 
statement, as you would any other PHP function library or class. 

For the most part, PEAR is to PHP as the Comprehensive Perl Archive Network (CPAN) is to Perl. It 
has many parts, but the best known and most frequently used is a library of open source PHP code 
modules that may be accessed in an automated way. The PEAR module management system makes 
it easy for you to keep a server's PHP installation up to date and outfitted with the elements it needs 
to do its job (for example, with the PEAR DB classes for standardized database access and the PEAR 
LDAP classes for accessing a corporate directory). You can run the package manager as an automated 
routine that checks for updated versions of your installed packages every week, if you like. 

Other parts of the PEAR project include: 

■ A set of coding standards that specifically applies to PHP modules distributed by PEAR 

■ The PHP Foundation Classes (PFC), which are a few especially worthy PEAR classes dis- 
tributed with the main PHP package 

■ Various code archives and mailing lists for the people doing PEAR module development work 
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The PHP Extension Community Library (PECL) is a collection of PHP extensions (written in C as all 
PHP extensions are) which are relatively rarely used and therefore do not need to be part of the core 
PHP distribution (which was threatening to become too large and unwieldy). PECL used to be part 
of PEAR, but has been split off for separate management. PECL and PEAR share the same automated 
distribution tool, though, and so remain related projects. The key difference between PEAR modules 
and PECL modules: PEAR modules are written in PHP and may be included in PHP programs as 
required. PECL modules are written in C, and may be incorporated into the PHP engine itself by the 
normal process of recompiling. 

The PEAR Package System 

The PEAR package system is an archive of compressed files (tar files compressed with gzip), each of 
which contains a series of PHP files and a manifest file in XML format. Each archive, when incorpo- 
rated into a PHP installation on a server (by means of the automated package-management system 
that's discussed later in this chapter), adds to the overall collection of functions and classes a devel- 
oper can invoke in his or her code. Widely used packages handle database abstraction, the inter- 
pretation of various file formats, the implementation of industry-specific algorithms, and all kinds 
of convenience functions. The universe of PEAR packages is large and expanding, and because the 
packages are of such high quality, you should make use of them in your own code if you can. 

The PEAR homepage is http://pear.php.net. 

A sampling of PEAR packages 

Here's a much-abridged list of PEAR packages. The package name generally describes its function: 

■ A u t h — User authentication 

■ Benchmark — Performance calibration 

■ DB — Database connectivity 

■ Calendar — Calendar objects and functions 

■ Archive_Tar — Interaction with tar files 

■ Archive_Zip — Interaction with Zip files 

■ HTTP — Manipulation of the HTTP protocol 

■ I m a g e_B a r c o d e — Barcode generation 

■ 1 1 8 N — Internationalization tools 

■ Log — Logging 

■ Mail — Interaction with POP, IMAP, and SMTP 

■ Oggvorbis — Interpretation of the Ogg Vorbis open-source audio file format 
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■ Tree — Tree structures for organizing objects 

■ SOAP — Implementation of the SOAP protocol 

Aside from enabling PHP server administrators to incrementally adjust the capabilities of their sys- 
tems, the PEAR package system is a way of dividing the labor involved in expanding the capabili- 
ties of PHP. Each of the many packages in the system — there are more than 250 as of this writing 
— has a separate development team behind it, complete with a project lead and several other con- 
tributors. Individual packages have version numbers and (usually) their own supporting documen- 
tation. Packages may depend on other packages (meaning that the depended-upon package must be 
installed); managing these dependencies is one function of the PEAR package management tool. 

How the PEAR database works 

The PEAR database serves two purposes: it is by design accessible to human readers as well as to 
the PEAR package-management client. You can use an ordinary web browser to navigate around the 
HTML documents at the PEAR site (http://pear.php.net), or you can use the package manage- 
ment client to interface with it via a Web service interface. 

Either way, the PEAR repository is organized as a tree, with related packages grouped into hierar- 
chies (though hierarchical relationships do not necessarily indicate dependency relationships among 
packages). The PEAR community manages what goes into the tree, determining when development 
on a particular package has progressed far enough to warrant a new release into the publicly avail- 
able repository. 

The Package Manager 

If, like most people, you're planning to use the PEAR repository as a resource rather than as an 
entity to which to contribute, your main interaction with it will be through the PEAR Package 
Manager. The package manager is a command-line program that interacts with the online repository 
and allows you to download, install, and uninstall PEAR packages according to your requirements. 
This remainder of this section shows you how to get and use the PEAR Package Manager. 

7T7P- "■' Remember that if you just want to use PEAR's DB, Net_Socket, Net_SMTP, Mail, XM L_ 
■""^^^^^ Parser, or phpllnit modules, you do not need to install the PEAR Package Manager or 
any packages! These packages, which are collectively referred to as the PEAR Foundation Classes, are 
bundled with PHP. 

Installing the PEAR Package Manager on Linux 

Assuming that PEAR is no longer included in PHP, or if you're running an older version of PHP 
under Linux (really old, older than version 4.3), you'll need to install the PEAR Package Manager by 
means of a two-part command. The command looks like this: 

$ lynx -source http://pear.php.net/go-pear | php 
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That command opens up the specified URL (which you can examine yourself through an ordinary 
web browser) with Lynx, a text-only HTTP client (certain Linux distributions have similarly func- 
tional programs with different names, such as 1 i n ks under Red Hat Linux). The URL contains text 
that defines a PHP program. The command line pipes that text to the PHP engine, thus allowing it 
to be interpreted. 

Updating the Package Manager 

Later, you may want to go through the g o - p e a r procedure again to update your system and make 
sure it's aware of the latest contents of the PEAR repository. You may want to do this every few 
months if you use PEAR packages very frequently or don't reinstall PHP very often. However, most 
people will find that getting a new version of the PEAR Package Manager every time you install a 
new version of PHP is frequent enough. The basic procedure is to go to http://go-pear.org and 
save the file there — there is only one — as go-pear. php in a directory that's accessible to your 
PHP compiler. 

Figure E-l shows the go-pear web site. 



FIGURE E-1 



The go-pear web site 



^1 hup:. v go pear. org/ - Miciosofi Internet Explorer 



| F4c £r£t Vtftw Ffiworfa* tOOjj Help 



| 4*B*A » ^ * @ g] jj} ] ^SMrth ^Favorites ^Hfetwy | L^- ^ B 



Address |^] hH(p://gtp-peiir.or^ 



3 IjUrks 



?php ffi echo; echo "YOU NEED TO RUN THIS SCRIPT WITH PHP NOU ! "; echo; echo "Try this: lynx 

A h 

I PHP Version 1 | 



| copyright (c) 1937~2QQ2 The PHP Group 

| This source file is subject to version 2.02 of the PHP license, 

| that is bundled uith this package in the file LICENSE, and. is 

| available at through the world~wide-web at 

| http : / / www . php . net / 1 icense/ 2 02 . txt. 

| If you did not receive a copy of the PHP license and are unable to 

| obtain it through the world-wide -web, please send a note to 

| lieense@php.net so we can mail you a copy immediately . 



I 



I Authors: Tomas V.V.Cox <cox@ ideenet . com> 

| Stig Sitther Battken <stig@php.net> 

| Christian Dickmann <dickmann@php.net> 

I Pierre-Alain Joye <pajoye@pearfr.org> 

?Id: go-pear, v 1.55 2003/11/18 18:57:30 pajoye Exp 5 

Automatically download all the files needed to run the "pear" command, 
(the PEAR package installer) . Requires PHP 4.1.0 or newer. 

Ins tal lat ion : L mux 
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After saving go-pear. php, go to the command line and run this command: 
php go-pear. php 

You should see output similar to the code above. With that done, you're again ready to make use of 
the PEAR Package Manager. 

Using the Manager 

The PEAR Package Manager has a command-line interface that is common to all versions of PHP 
The instructions in this section apply equally to all Unix variants (including Linux) and to Microsoft 
Windows. 

The key executable of the PEAR Package Manager is pear. It resides in your PHP home directory, 
alongside the PHP interpreter itself. 

Automatic package installation 

Once you have PEAR installed and updated, you can install any package you've downloaded. The 
generic syntax for doing an automatic installation of a package is this: 

pear install <package> 

In that syntax, <package> is the name of a PEAR package. All available packages are listed at 
http://pear.php.net/packages.php. You can also run: 

pear remote-list 
to see what's available. 

Here's an example of installing the PEAR DB package via the automatic PEAR Package Manager method: 

C:\PHP>pear install DB 
downloading DB-1 . 5 . 0RC2 . tgz ... 

Starting to download DB-1 . 5 . 0RC2 . tgz (68,128 bytes) 

done: 68,128 bytes 

install ok: DB 1.5.0RC2 

Automatic package removal 

Uninstalling a package is just as easy as adding one. The generic syntax looks like this: 

pear uninstall <package> 

To uninstall the DB package, then, we'd do this: 

C:\PHP>pear uninstall DB 
Uninstall ok: DB 
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If you're not sure what packages are installed locally, run the following command to find out: 
pear list 

Semiautomatic package installation 

If, for some reason, you downloaded a PEAR package in the form of a .tgz file, you can later use the 
PEAR Package Manager to install it, even if there's no connection to the Internet available. You just 
point the pear command at the local file, as follows: 

pear install HTML_BBCodePa rser- 1 . 0 . tgz 
Using PEAR packages in your scripts 

Once you've installed the PEAR modules you wish to use, you should make sure the location is 
included in the i ncl ude_path variable of your php . i ni file. This location can be tricky — it will 
probably be / usr/local/lib/phpon Unix servers and whatever you specified during the g o - p e a r 
procedure on a Windows server. Once you've done that, you can include these libraries from any PHP 
script with a normal include directive: 

<?php 

i ncl ude_once ( 'Mail . php ' ) 

// Your code which uses PEAR Mail functions here 
?> 



PHP Foundation Classes (PFC) 

The PEAR Foundation Classes (PFC) are a subset of the PEAR module repository. The modules 
that are part of the PFC are written to an especially high standard of quality, have been extensively 
tested, and are considered very stable and reliable. The PFC are distributed with PHP itself, so you 
do not have to download or install them separately. As of PHP5, the members of the PFC are these 
packages: DB, Net_Socket, Net_SMTP, Mai 1 , XML_Parser, and phpUnit. 

In writing modules for the PFC, programmers must aim for broad compatibility. They should avoid 
using any resource that's particular to a specific operating system, and try to take input and give 
output in the most generic possible form (for example, in plain text rather than as SOAP-formatted 
messages). Programmers also need to keep in mind possible future developments in PHP itself — 
information that can be gleaned from mailing lists and other community resources — and write their 
software so it is unlikely to break when new releases appear. 
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PHP Extension Code Library (PECL) 

The PHP Extension Community Library (PECL) is conceptually very similar to PEAR, and in fact they 
share the PEAR Package Manager infrastructure (that is, PECL modules can be accessed and installed 
via the PEAR Package Manager). The main difference is that PECL is concerned with extensions to 
PHP itself, in the form of C modules that attach to the PHP engine. As C programs, extensions typically 
execute faster and more efficiently than the modules contained in the PEAR repository. 

PECL used to be called the PEAR Extension Code Library and was spun off from PEAR in October 
2003. The new PECL homepage is http : / /peel . php . net. 



The PEAR Coding Style 

Newspapers (as well as publishers of books!) spend a lot of time and effort establishing style rules 
that govern how their writers use language. Are people identified by their last names (as in The 
Washington Post) or by their honorifics and last names (as in The Economist and The New York Times)! 
It's a matter of style. 

The same sorts of questions arise among programmers, except that the issues at stake are usually 
matters of formatting rather than syntax. Where do brackets go, and how is code laid out on a page? 
It's important to have standard (if arbitrary) answers to these questions, because a standard style can 
be a real aid to error-spotting and maintainability. 

PEAR defines its style rules online at http : / /pear . php . net/manual /en/ standards . php. This 
section calls attention to some of the most important ones. 

Indenting, whitespace, and line length 

Code is much easier to read if you use indentation to indicate the relationship among lines of code 
that are tied together in a common functional block, as well as whitespace to logically group ele- 
ments. The following code is hard to read, though it will run perfectly fine. 

switch ($flag) ( 
case 1 : 
doWork( ) ; 
break ; 
case 2 : 

doOtherwork( ) ; 
break ; 
def aul t : 
doNothi ng( ) ; 
break ; 
} 
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On the other hand, this code: 

switch ($flag) { 

case 1: 

doWork( ) ; 
break ; 

case 2: 

doOtherWork( ) ; 
break ; 

def aul t : 

doNothi rg ( ) ; 
break ; 

} 

is both functional and more easily understood. Spotting syntax errors is hard enough; don't make 
the job harder by clumping your code together sloppily 

One of the big religious arguments in programming is the number of spaces to indent each new code 
block — some people insist that two saves space, others swear by four, and some outliers actually 
employ eight-space indents (the horror!). Over time and in groups, four has come to be a standard 
compromise position, adopted by many open source projects — including PEAR. If you want your 
code to be accepted into PEAR, it must use four-space indents. 

Because different editors on different platforms interpret tab characters differently, it's recommended 
that you use groups of four space characters in all places you would, under other circumstances, use 
a tab character. 



Formatting control structures 

Control structures — such as if, if/else, if/elseif, and switch statements — can be confus- 
ing if not properly formatted. PEAR has recommended styles for all of these language constructs. 

if Statements 

A simple two-test i f statement should be formatted like this: 

if ( (conditionl) && ( condi ti on2 ) ) { 
doSomething( ) ; 

} 

Note that the opening bracket appears on the same line as the conditions (so-called Kernighan and 
Ritchie, or K&R, braces), and that there are brackets even though there is only one line of code in 
the conditional block. That way, the fact that it's a block is obvious, and there's no need to remem- 
ber to add them when further lines of code are added in the future. Also note that there should be a 
space between a conditional statement and the expression being tested. 
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if/else Statements 

An i f /el se statement builds on the basic i f format: 

if ( ( condi ti onl ) && ( condi ti on2 ) ) ( 

doSomethi ng ( ) ; 
I else ( 

doSomethi ngEl se( ) ; 

} 

The else appears on the same line as the closing bracket that terminates the 1 f block. 

if/elseif Statements 

An i f /el sei f statement looks just like an i f /el se statement in terms of formatting: 

if (( condi ti onl ) && ( condi ti on2 ) ) ( 

doSomethi ng ( ) ; 
I e 1 s e i f ( 

doSomethi ngEl se( ) ; 

} 

switch Statements 

Switch statements rely on whitespace and indentation to make code blocks obvious: 
switch ($flag) ( 

case 1 : 

dowork( ) ; 
brea k ; 

case 2: 

doOtherWork( ) ; 
brea k ; 

def aul t : 

doNothi ng( ) ; 
brea k ; 

} 

Formatting functions and function calls 

Much of PHP is concerned with defining functions, then making calls to them, and obviously code 
libraries like PEAR will be almost all functions. Properly formatting your functions can make it 
more obvious what's going on and can therefore make debugging and maintenance easier. 

The PEAR style rules mandate that functions be defined with both their beginning and ending 
braces flush with the left margin, like this: 

function my Functi on ( ) 
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{ 

// Function code goes here. 

} 

This makes function definitions (which use braces) stand out from conditional blocks (which 
also use braces). Furthermore, the standards require that code within the function be indented. 
Everything is indented at least four spaces; some segments may be indented further: 

function myFunctionU 

{ 

doSomethi ng( ) ; 
if (lis) ( 

doSomethi ngMore( ) ; 

} 

) 

If your function takes arguments, be sure to order them so that arguments with default values go at 
the end of the list, like this: 

function my Functi on ( $a , $b, $c= ' Def aul t ' ) 

{ 

doSomethi ng( ) ; 
if (lis) ( 

doSomethi ngMore( ) ; 

} 

} 

Also note that there should be no spaces between the name of the function and the parentheses 
containing arguments. Again, this helps visually distinguish functions (which use parentheses) from 
expressions (which also use parentheses). 

It is important that functions return something. The return value will either be a value that resulted 
from the function's processing or a Boolean value (true or false) to indicate success or failure. 



Summary 

In this appendix, you learned about PEAR, a previously included framework for PHP community- 
based projects that extend the capabilities of the language. PEAR exists to facilitate the ongoing 
development and widespread distribution of handy toolkits. 

At the center of PEAR is its repository, an online database that contains the accumulated body 
of PEAR packages. This repository has an HTML interface as well as an XML_RPC (Web ser- 
vices) interface, which means that you can browse it manually or interact with it via a specialized 
command-line program: The PEAR Package Manager. The PEAR Package Manager allows you to 
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quickly see what's in the PEAR repository, download what you want, and install some or all of what 
you download. Particularly important PEAR packages are part of the PHP Foundation Classes (PFC). 

Another element of the PEAR community is a definition of a coding standard, which specifies how 
functions should be defined, comments placed, and brackets structured in various parts of PHP pro- 
grams. It's meant to ease readability and make life easier for documentation writers. 

PEAR shares its automated package-distribution scheme with PECL, which manages PHP extensions 
written in the C language. 

PEAR represents an invaluable resource to PHP programmers of all levels. Make sure that the PEAR 
Package Manager is installed on your PHP server, and make full use of its resources. When you're 
ready, join the development effort and contribute to the growth of PHP. 
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abs function, 155, 159 

absolute links from relative links, 384-385 

absolute value, 155, 159 

abstract classes 

declaring, 328 

designated, 352 
abstract data structures, 363 
abstraction, procedural, 60 
access 

members, 319, 325-327 

source code, 474-475 
access. conf file, 489 
access.log file, 514-515 
accessor functions, 354 
Acos function, 462 
ACTION attribute, 100-101 
Action directive, 475, 490 
actual parameters, 87-89 
add function, 329 
add_l function, 451 
add_new_country function, 250 
add_point_to_path function, 705 
addHiddenVariable function, 347 
addlnputButton function, 347 
addlnputForm function, 347, 352 
addition, 154 

arbitrary-precision function, 466 

assignment operator, 156 

increment operator, 155-156 
additionalAttributes function, 351 
AddModule setting, 491 
addslashes function, 127-128, 300 
AddType directive, 475, 490 
affectedRows function, 573 
aggregating query results, 289 
algorithm efficiency, 534 
alignment in format strings, 129 
allowed elements in XML documents, 652 
alpha value for transparency, 699 
ALTER privilege, 209 
ALTER TABLE statement 

indexes, 286-287 



primary keys, 284-285 

structure, 204 
alternate control syntaxes, 79-80 
American Standard Code for Information Interchange 

(ASCII) encoding, 662 
ampersands (&) 

GET method, 101 

logical operator, 61 

passing arrays by reference, 145 
anchor tags for links, 381-382 
anchoring characters in regular expressions, 379 
anchortext for links, 381-382 
and operator, 37, 61 
angle_given_sides function, 774-775 
answer handling in Certainty Quiz, 753 
answer_string function, 543 
anti-style sheets, 545 
Apache modules, 485 
Apache Server, 7 

building, 23 

in CentOS installations, 21 

configuration files, 489-491 

extensions setup for, 24 

log files, 514-515 

RPM versions, 20 

on Windows, 25-26 
APC Accelerator, 495 
appendChild function, 659 
application platform considerations, 4 

cost, 4 

cross-platform compatibility, 7 
ease of use, 5 
extensions, 8 
feature development, 8 
HTML-embeddedness, 5-7 
proprietary standards, 8-9 
stability, 7-8 
user communities, 9-10 
apt-get command, 190 

arbitrary-precision math functions, 465-466 

configuration option, 488 

converting code to, 467-469 

example, 466-467 
area of intersecting circles, 773-776 
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area_to_radius function, 775 
args_as_array_l function, 446 
arguments and parameters, 36, 83 

arrays for, 445 

default, 444 

echo, 56 

functions, 86-89 

GET method, 100-102 

multiple, 445-447 

number mismatches, 89-90, 178 

Perl, 803-804 

POST method, 104-105 

print, 56 

unquoted, 303-304 

variable number of, 443-447 
arithmetic operators, 154-155 

C language, 796 

Java, 620 
array construct, 134-135, 138 
array_count_values function, 359, 362 
array_flip function, 359, 362 
array_keys function, 358, 362 
array_merge function, 360, 362 
array_pad function, 361, 363 
array_pop function, 364-365 
array_push function, 364-365 
array_reverse function, 359-360, 362 
array_shift function, 364-365 
array_slice function, 361, 363 
array_splice function, 361-363 
array_to_bar_graph function, 691-692 
array_unshift function, 364-365 
array_values function, 358, 362 
array_walk function, 149 
arrays, 131 

associative, 132-133 

C language, 797 

conversions with, 437, 440 

creating, 134-136 

current and next functions, 143-145 
deleting elements, 140 
each function, 147-149 
fetching, 223 

flipping, reversing, and shuffling, 359-360 

foreach function, 142-143 

functions returning, 136 

indices, 135-136 

inspecting, 139 

iteration support, 140-142 

keys extraction, 147 

keys retrieval, 358-359 



merging, padding, slicing, and splicing, 360-362 

multidimensional, 137-139 

as multiple-argument substitutes, 445 
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printing, 367-368 

resetting, 145-146 

reverse order, 146 

sorting, 366-367 

stacks and queues, 363-365 

superglobal, 90, 101-102, 110 

testing for, 436 

transformations, 357-358 

translating with variables, 365-366 

undefined, 177 

uses, 131 

value retrieval, 136-137, 358-359 

walking, 149 
arsort function, 367 
articles, 825 

ASCII (American Standard Code for Information 

Interchange) encoding, 662 
Asin function, 462 
asort function, 367 
assignment 

arrays, 134 

automatic, 106 

conversions in, 436-441 

expressions, 37-38 

objects, 324 

strings, 116 

types, 45-46 

variables, 41 
assignment operators, 156-157 

C language, 796 

concatenation, 115-116 

concise code from, 537 

Java, 620 
associative arrays, 132-133 
associativity of expressions, 36-37 
asterisks (*) 

assignment operators, 156 

multiplication, 154 

precedence, 158 

regular expressions, 375, 378 
at signs (@) 

with functions, 220 

Java, 627-628 

Perl, 803 

SQLite, 607 
Atan function, 462 
Atan2 function, 462 
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attacks 

reading files, 475-477 

running arbitrary programs, 477-479 

site defacements, 472-473 

source code access, 474-475 
attributes 

OOP, 316 

XML, 649, 654 
authentication, 429-430 
auto-append-file setting, 493 
auto-incremented primary keys, 284 
auto-prepend-file setting, 492 
auto_start variable, 421 
automatic type conversion, 45 
automatic variable assignment, 106 
availability service, 533-534 
average function, 289 
awkward programming, avoiding, 187 

B 

back-tick operator ('), 478 
backend servers, 811 
backslashes (\) 

regular expressions, 375-376, 378-379 

strings, 52-53, 114-115 
backups, database, 206, 212-214 
bar_graph.php file, 691-692 
bar_graph_form.php, 693-694 
base cases in recursive functions, 97 
base classes, 315-316 
base conversions, 457-460 
baseconvert function, 459 
basename function, 401 
batch editor, 594-604 
batch_upload_new.php file, 594, 600-604 
BC functions, 465-466 

configuration option, 488 

converting code to, 467-469 

example, 466-467 
better_deal function, 87-88 
BIGINT data type, 231 
BINARY data type, 232 
binary numbers, 459-460 
binary strings, testing for, 436 
BinDec function, 459 
binding, 92 

to cursors, 583 

early vs. late, 317 

functions, 366 

in sessions, 414 
BIT data type, 230 
blank images, 710 



blank lines, 32 
blank pages, 167 
BLOB data type, 232 
blocks, creating, 38-39 
Book class, 341-342 
books in XML format, 651-652 
BOOL data type, 230 
BOOLEAN data type, 230 
Boolean values, 49 

for conciseness, 538-539 

constants, 49, 60 

conversions with, 437 

doubles as, 50 

examples, 50 

expressions, 37, 60 

Java, 620 

MySQL, 230 

testing for, 436 
boolval function, 437 
bottlenecks, 494, 535 
bounded loops, 71, 74-75 
box_query function, 280-281 
<BR> tag, 57 
braces ({}) 

blocks, 38-39 

class definitions, 318 

functions, 86 

if-else structures, 66 

interpolation, 114-115 

string variables, 115 
brackets ([]) 

arrays, 132 

regular expressions, 375, 378 
branching, 59 

HTML mode, 68-69 

if-else, 65-69 

switch constructs, 69-70 
break statements 

in loops, 76-78 

Perl, 805 

with switch, 69-70 
broken images, 711 
broken SQL statements, 301-303 
Browse function, 634, 636 
browsers 

for images, 696 

PHP code in, 167-168 
browsersniff.php file, 635 
buckets, splitting strings and files into, 387 
buffers, testing for, 436 
bug types, 513-514 
building Apache server, 23 
built-in functions, 84 
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learning, 815 

PHP code, 799-800 

PHP differences, 796-798 

PHP guide, 798-799 

PHP similarities, 34, 795-796 
C-style multiline comments, 39 
caches 

Oracle, 579 

products, 495 
Calculator class, 328-329 
calendar_form_string function, 543 
calendar.php file 

maximal PHP style, 541 

medium PHP style, 542-543 

minimal PHP style, 540 
calendars 

configuration option, 488 

conversion functions, 407-408 
call-by-reference functions, 448-450 
call-by-value functions, 145, 447-448 
call_user_method_array function, 336 
calling functions 

parent constructors, 329-331 

parent functions, 329 

syntax, 83 
camelcaps naming style, 529 
canonical PHP tags, 28 
capitalization 

function names, 87 

Oracle, 582 

strings, 127 

variable names, 528 
carets ( A ) in regular expressions, 375, 379 
carriage-return characters 

escape sequence, 53 

as white space, 34 
Cartoons databases, 557-565 
Cascading Style Sheets (CSS), 13-14, 545 
case folding, 661-662 
case functions, 126-127 
case sensitivity, 35 

filenames, 529 

keys and keywords, 491 

problems, 175 

SAX, 661-662 

substring searches, 118, 121 

variables, 106 
catch blocks, 93-94, 500 
ceil function, 158-159, 440, 458 



centering text, 785 
CentOS, PHP installation on, 21-22 
Certainty Quiz, 727 
code, 731-732 

certainty_utils.php, 755-759 
dbvars.php, 763-764 
game_class.php, 746-753 
game_display_class.php, 735-744 
game_parameters_class.php, 753-755 
game_text_class.php, 744-746 
index. php, 732-735 
question_class.php, 759-763 
concepts, 727-728 
database, 764-768 
design considerations, 768-769 
overview, 728 
rules, 729, 731 
sample screens, 728-729 
summary, 769 
version, 728 
certainty_utils.php file, 732, 734, 755-759 
cgi-bin directory, 474 
CGI compile-time options, 488-489 
CGI-style, 541 

chained_code function, 453-454 
chained subclassing, 322-324 
CHANGE MASTER TO command, 216 
changed file contents, checking for, 387 
CHAR data type, 232 
characterData function, 661 
characters, 115. See also strings 

finding, 118-119 

MySQL, 232 

regular expressions, 375, 378-379 
CHECKBOX elements, 267-269 
checkdate function, 407 
checkdnsrr function, 404 
_checksumChecks function, 742 
checksumming messages and files, 387 
chgrp function, 401 
child classes, 315-316 
chmod function, 401 
choke_and_die function, 587 
chop function, 123-124 
chown function, 401 
chr function, 91, 440-441 
cipher substitution function, 450-454 
circle_intersection_area function, 775-776 
circles 

drawing, 784-785 

intersecting, 773-776 
city_by_number function, 143 
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class_exists function, 335 
class keyword, 318 
classes, 316 

abstract 

declaring, 328 
designated, 352 

defining, 318-319 

functions, 317, 328-329 

genealogy, 337-340 
ClassNotDefined error, 628 
CLASSPATH setting, 623-624 
ClassToSerialize class, 332 
ClassToSerialize2 class, 333-334 
cleanup functions for strings, 123-124 
clearstatcache function, 400-401 
client commands in MySQL, 208 
client-side technologies, 13-15, 17 
client to server communication, 15 
clock arithmetic, 155 
cloning functions, 95 
closelog function, 403 
code 

reuse, 535, 537 

separating from design, 544-546 

source, 474-475 
codebases, 825-826 
coercion, type, 436-441 
collisions 

strings, 387 

writes, 576 
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else and elseif, 80 

OOP syntax, 328, 330 

ternary operator, 65 
color in images, 698-700 
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headers, 242 

matching to variables, 340-342 

SQL databases, 194 

tables, 238 
command-line PostgreSQL utilities, 553 
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arguments, 36, 83, 86 

in for statements, 73 

global variables, 91 

problems, 303 
comment_edit.php file, 264-267 
comments 

Perl, 805 

readability, 526-527 
styles, 39-40 



Common Log Format, 514-515 
communication in server-side scripting, 15 
Community Server edition, 4, 189 
compact function, 365-366 
comparing strings, 119 
comparison operators, 62-63, 157 

C language, 796 

non-integers, 64 

precedence, 63 

strings, 63-64 
compatibility, platform, 7, 9 
compile-time bugs, 513 
compile-time options, 484-489 
compiling 

C language, 798 

Java, 621 

Perl, 801 

complex mapping of tables, 245-249 
complex printing example, 248-249 
complex variable expressions, 115 
compound types, 46 

Comprehensive Perl Archive Network (CPAN), 806, 830 

compression of images, 696 

computeChecksum function, 343 

Computer Emergency Response Team (CERT) site, 480 

concatenation, 115-116 

concatenation operator, 115-116 

conciseness 

guidelines, 537-539 

limitations, 536 
Concurrent Versions System (CVS), 532 
configuration, 483 

Apache files, 489-491 

compile-time options, 484-489 

environment variables, 483 

overview, 484 

summary, 495-496 
confirmOne function, 643 
connect function, 573 
connection-level errors, 581 
connections 

efficiency, 279-282 

multiple, 226-227 

MySQL, 208, 219-220 

PEAR DB, 570-571, 573 

problems, 295-297 
consolidating forms and form handlers, 109-110 
constants, 44 

Boolean, 49, 60 

math, 455-456 

OOP, 327-328 
construct function, 317, 320 
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constructive functions, 360 
constructors, 315, 317 

functions, 319-320 

parent, 329-331 
continue statements 

in loops, 76-78 

Perl, 805 
control structures, 59-60 

alternate, 79-80 

Boolean expressions, 60-62 

branching, 65-70 

C language, 796 

comparison operators, 62-64 

loops. See loops 

PEAR, 837-838 

summary, 81-83 

terminating execution, 80-81 

ternary operator, 65 
conversion specifications in format strings, 129 
conversions 

to arbitrary-precision values, 467-469 

base, 457-460 

C language, 797 

calendar systems, 407-408 

numbers, 154 

relative links to absolute, 384-385 

types, 45, 436-441 
$_COOKIE array, 110 
cookie-based sessions, 412 
cookie_lifetime variable, 421 
cookies, 422 

deleting, 425 

examples, 423-424 

HTTP headers, 428-430 

pitfalls, 426-428 

privacy, 424 

reading, 425-426 

refusal, 427-428 

setting, 422-423 
coordinate systems for images, 699 
copy function, 401 
core scripting engine and tools, 824 
Cos function, 462 
cosmetic issues for tables, 242 
costs, 4 

count function, 139, 289 
count_chars function, 388-389 
count_values function, 359 
countdown function, 96-98 

CPAN (Comprehensive Perl Archive Network), 806, 830 
crack! program, 480 
crackers, 472 



create definitions, 203 
CREATE privilege, 209 
create_randomized_array function, 758-759 
CREATE TABLE statement, 203, 554-555 
CREATE USER statement, 555 
createdb command, 553 
createElement function, 658 
createTextNode function, 659 
cross-platform compatibility, 7 
crypt function, 477, 480 
CSS (cascading style sheets), 13-14, 545 
curly braces ({)) 

blocks, 38-39 

class definitions, 318 

functions, 86 

if-else structures, 66 

interpolation, 114-115 

string variables, 115 
current function, 143-145 
current pointer, 141, 148 
_currentQuestionString function, 739-740 
cursors, 583-584 
Customer class, 354 
CustomException class, 502 
customized_greeting function, 450 
CVS (Concurrent Versions System), 532 
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data caching 

Oracle, 579 

products, 495 
data entry script, 723-724 
data information functions, 225-226 
data manipulation statements, SQL, 195 
data movement in Web services, 675-676 
data munging, 577 
data sets, fetching, 222-225 
Data Source Names (DSNs), 568-570 
data types. See types 

data visualization, Venn diagrams for. See Venn diagrams 
databases 

administering, 207 

backups, 206 

Certainty Quiz, 747, 764-768 
compile-time information, 486 
connectivity, 8 
creating, 229-231 
design, 201-204 
efficiency, 279 

connections, 279-282 

date and time fields, 290-291 
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indexing, 282-287 

last inserted row, 291-292 

looping, 288-290 

table design, 287 
forms. See forms and form handlers 
multiple connections, 226-227 
MySQL. See MySQL databases 
Oracle. See Oracle databases 
overview, 185-186 
passwords, 205-206, 229 
PEAR, 832 

permissions, 204-205 

PostgreSQL. See PostgreSQL databases 

purpose, 186-187 

queries. See queries 

recovery, 217-218 

replication, 214-216 

SQLite. See SQLite databases 

supported, 187-188 

tables. See tables 

visualizing, 785-790 
date_add function, 290-291 
DATE data type, 231 
date fields, 290-291 
date function, 406 
date functions, 405-407 
date_prefs.php file, 271-274 
date_subtract function, 290 
DATETIME data type, 230-231 
day_of_week_string function, 543 
DB_Common class, 573-574 
DB_Result class, 574 
db_visualization.php file, 772, 788-790 
dbSpecs.php file, 569 
dbvars.php file, 732, 763-764 
deb package, 20 
Debian Linux, 20 

MySQL Server installation on, 190 

PHP installation on, 22 
debugging, 307-308, 511 

bug types, 513-514 

error logging, 517 

error reporting, 516-522 

with exceptions, 508-509 

learning from, 814 

strategies, 512-513 

summary, 523 

web server logs, 514-516 
DEC data type, 231 
DecBin function, 459 
DecHex function, 459 
DECIMAL data type, 230-231 
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concatenation operator, 115-116 

floating-point numbers, 47 

format strings, 129 

regular expressions, 375 
declarations 

document type, 653 

Perl, 802 

types, 45 

variables, 40 
DecOct function, 459 
decrement operators, 155-156 
default arguments, 444 
default.txt file, 719 
default values, 41-42 
define function, 44 
defining 

classes, 318-319 

functions, 86-88 
delete function, 401 
DELETE statements 

indexing, 283 

working with, 200-201 
deleting 

array elements, 140 

cookies, 425 
delimiters, 371 
denormalized data, 199 
dependent code in control structures, 60 
derived classes, 316 
deselectAUOthers function, 643 
design 

Certainty Quiz, 768-769 

database, 201-204 

separating code from, 544-546 

tables, 287 
designated abstract classes, 352 

destruct function, 317 

destructive functions, 360 
destructors, 315, 317 
developers' lists, 819-820 
development tools, 26-27 
Devshed site, 825 

diagnostic print statements, 518-519 
dicing strings, 121 
die function 

in debugging, 167 

error checking, 227-228 

working with, 80-81 
die_silently function, 587 
digest mailing lists, 821-823 
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direct assignment of arrays, 134 
directory permissions, 392 
dirname function, 401 
— disable-force-cgi-redirect flag, 475 
disable_functions directive, 400, 492 
— disable-url-fopen-wrapper flag, 488 
disabled_functions directive, 399 
disconnect function, 571, 573 
disk_free_space function, 401 
disk space for indexes, 286 
disp_func_results function, 463-464 
display, Venn diagrams 

code, 784-785 

planning, 777-783 
display_bases function, 459 
display_cities function, 246-249 
display_db_query function, 243 
display_db_table function, 239, 243-244 
display_errors directive 

blank pages, 167 

security, 474 

setting, 516 

silent mode, 220 
display function 

ClassToSerialize, 332 

ClassToSerialize2, 334 

GameDisplay, 737-738 

TextBox, 320 

TextBoxHeader, 321-322 

TextBoxSimple, 318-319 
display_path function, 705-706 
displayEntryForm function, 767-768 
distractor_string function, 744 
_distractorString function, 740 
distributed computing, 677 
DivisibleByBad function, 538 
DivisibleByBetter function, 538 
division, 154 

arbitrary-precision function, 466 

assignment operator, 156 
division-by-zero warnings 

avoiding, 539 

handling, 178 
division table, 74-75 
.dll files, 25 

DNS-querying functions, 403-404 
do-while loops 

summary, 83 

syntax, 72 
doc_root setting, 493 
document elements in XML, 649 



Document Object Model (DOM). See DOM (Document 

Object Model) 
document type declarations, 653 
document type definitions (DTDs), 651-655 
documentation 

in debugging, 513 

functions, 84-86 
DocumentRoot setting, 490 
dollar signs ($) 

C language, 796 

missing, 170 

Perl, 802 

regular expressions, 375, 379 

strings, 54 

variables, 40 
DOM (Document Object Model) 

functions, 657 

overview, 656-657 

vs. SAX, 655-656 

working with, 657 
dom_example.php file, 657 
dom_polledit.php file, 669-672 
domains for cookies, 423 
DomAttr class, 658-659 
DomDocument class, 658-659 
DomNode class, 658-659 
domxml_ functions, 658 
dot object notation, 632 
dots (.) 

concatenation operator, 115-116 

floating-point numbers, 47 

format strings, 129 

regular expressions, 375 
DOUBLE data type, 231 
double_drop.html page, 638-642 
DOUBLE PRECISION data type, 231 
double quotes (") in strings, 52-53, 113-114 
double type, 47, 153 

as Booleans, 50 

C language, 796 

equality comparisons, 63 

MySQL, 231 

read formats, 48-49 

testing for, 436 

type contagion, 155 
doubleval function, 154 
download-docs.php file, 817 
downloading files, 397-398 
drawing coordinates and commands, 699 
DROP privilege, 209 
DROP statement, 204 
dropping tables, 203-204 
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DSNs (Data Source Names), 568-570 
DTDs (document type definitions), 651-655 
dyn_navigation.html page, 636-642 
dynamic Apache modules, 485 
Dynamic HTML, 13 
dynamic JavaScript, 636-642 

E 

E_ALL constant, 44 

e for scientific notation, 48 

e-mail 

client-side vs. server-side, 17 

sending. See sending 
each function, 147-149 
early binding, 317 
ease of use, 5 
easter_date function, 408 
easter_days function, 408 
echo statement 

in debugging, 512, 518-519 

strings, 56, 128 
Eclipse text editor, 27 
edit-compile-execute cycle, 621 
edit.php file, 562-564 
editing with HTML forms, 264 

CHECKBOX elements, 267-269 

RADIO elements, 269-274 

SELECT elements, 274-277 

TEXT and TEXTAREA elements, 264-267 
editors 

batch, 594-604 

PHP, 669-672 

point, 584-594 

text, 27 
efficiency, 534-536 

vs. conciseness, 536 

database. See databases 
elements in XML, 649, 654 
ellipses, 784-785 
else branches, 65-69 
Elseif statements, 67, 69 
elsif statements, 805 
embedded HTML, Java, 621-622 
embedded images, 702 
empty elements in XML, 649 
empty values in array iterations, 147-149 
— enable-bcmath flag, 488 
— enable-calendar flag, 488 
— enable-discard-path flag, 474, 488 
— enable-force-cgi-redirect flag, 475, 489 
— enable-url-includes flag, 488 



encapsulation, 315, 317 
encryption 

form data, 105 

passwords, 205, 429, 477 
end function, 145-146 
end-of-file tests, 400 
end-of-line characters, 57 
end tags for links, 381-382 
endElement function, 661 
endfor statement, 79 
endif statement, 79 
endswitch statement, 79 
endwhile statement, 79 
entry_form.php file, 732, 766-768 
ENUM data type, 232 
$_ENV array, 110 
environment variables, 483 
equal signs (=) 

comparison operators, 62-63, 157 

GET method, 101 

mistakes using, 63 

string comparisons, 119 

variable assignment, 41 
equality comparisons on doubles, 64 
ereg function, 376-377 
ereg_replace function, 377 
eregi function, 377 
eregi_replace function, 377 
error_append_string setting, 492 
error.log file, 514 

errorjog function, 167, 228, 302, 474, 508-509, 522 
error_msg function, 506, 508-509 
error_prepend_string setting, 492 
error_reporting function, 44 
error_reporting setting 

argument number mismatches, 89 
default value, 492 
report levels, 517 
errors and error checking. See also exceptions 
handlers 

defining, 506-507 
functions, 93-94 
Java, 627-628 
MySQL, 227-228 
native, 504-506 
Oracle, 581 
reporting, 518 
debugging, 516 
errorjog, 522 
logging, 517, 521 
Oracle, 581 

print statements, 518-519 
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syslog, 519-521 

unassigned variables, 41 

var_dump, 519 
tables, 242 
triggers, 507-508 
escape characters and sequences 
functions, 127-128 
from HTML, 28-32 
Oracle, 580 

regular expressions, 379 

strings, 53, 580 

XML, 650 
escape_html function, 586 
escape_sq function, 586 
escapeshellcmd function, 479 
/etc/passwd file, 477 
etiquette for mailing lists, 821 
evaluating expressions, 36-37 
event hooks, 660 
Event Viewer 

error severity levels, 521 

IIS logs, 516 
Exception class, 94, 499-501 
exceptions, 497. See also errors and error checking 

Certainty Quiz, 734-735, 769 

error handling, 497-499, 506-507 

Exception class, 499-500 

functions, 93-94 

Java, 627-628 

limitations, 504 

logging and debugging, 508-509 
native errors, 504-506 
subclass defining, 502-504 
summary, 509 
throwing, 501 

triggering user errors, 507-508 

try/catch blocks, 500 
exclamation points (!) 

comparison operators, 62, 157 

logical operators, 61 
exec function 

PHP, 478 

SQLite, 606 
exec_time function, 493-494 
execute directory permission, 392 
execution 

Oracle, 581 

terminating, 80-81 
existence of files, 400 
exit construct, 80 
exp function, 461 
expat parser, 660 



expiration date of cookies, 422 
explicit types conversions, 437-438 
explode function, 373-374 

conversions, 396, 440-441 

in performance, 494 
exponents, 461 

exporting functions for images, 701 
expressions 

assignment, 37-38 

Boolean, 37, 60-62 

evaluating, 36 

evaluation order, 36-37 

regular. See regular expressions 

tokens in, 35-36 

types, 37 
extends keyword, 318, 320 

Extensible Markup Language. See XML (Extensible Markup 

Language) 
extension setting, 297 
extension_dir setting, 623 
extensions 

Apache server, 24 

PHP, 8 
external DTDs, 653-655 
extract function, 365-366 
extracting array keys, 147 

F 

failover in Oracle, 579 
Faqts, 824-825 
fatal errors, 176, 504 
favorites.php file, 719-720 
fclose function, 399 
feature development speed, 8 
feof function, 400 
fetch method, 608-609 
fetchAU method, 609 
fetching data 

Oracle, 581-582 

PHP, 222-225 

SQLite, 608-609 
fetchlnto function, 574 
fetchRow function, 571, 574 
fgetc function, 397 
fgetcsv function, 401 
fgets function, 396 
fgetss function, 401 
fields 

date and time, 290-291 
offsets, 223 
tables, 238 
types, 287 
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file function, 397 
file_exists function, 400 
file_get_contents function, 396 
FILE privilege in MySQL, 209 
fileatime function, 401 
filectime function, 401 
filegroup function, 401 
fileinode function, 401 
filemtime function, 401 
tileowner function, 401 
fileperms function, 401 
files and filesystems, 391 

checksumming, 387 

closing, 399 

downloading, 397-398 

embedded images from, 702 

end-of-file tests, 400 

existence tests, 400 

functions, 392-393, 400-403 
calendar conversion, 407-408 
date and time, 405-407 
network, 403-405 

including, 30-32 

names, 528-529 

opening, 393-396 

permissions, 391-392 

reading, 396-397 

size, 396, 400 

splitting into buckets, 387 

writing, 398-399 
filesize function, 396, 400 
filetype function, 402 
filling functions, 701 
financial transactions, Oracle for, 576 
find_center_distance function, 783 
find_circle_centers function, 779 
finding. See searches 
finger function, 479 
first in, first out (FIFO) containers, 364 
FIXED data type, 231 
Flash animations, 13 
flipping arrays, 359-360 
FLOAT data type, 231 
float types, 47-48, 153 

conversions with, 433, 436-437, 440 

MySQL, 231 

read formats, 48-49 

testing for, 436 
floatval function, 437 
flock function, 402 
flood-fills, 784 
floor function, 158-159, 440 



FLUSH PRIVILEGES command, 211, 298 
FLUSH TABLES command, 215 
footer.inc file, 720-721 
footprints for Web services, 681 
fopen function, 383-384, 393-396 
for loops, 72-73 

example, 74-75 

summary, 83 
foreach construct, 142-143 
form_printer.php file, 346-352 
formal parameters, 87-89 
format strings, 129 
formats 

date, 406 

doubles, 48-49 

images, 696, 699 

integers, 47 
formatting form variables, 106-108 
formhandler.php file, 255-256 
forms and form handlers 

CHECKBOX elements, 267-269 

consolidating, 109-110 

database submissions, 254-264 

dynamically generated, 637-642 

OOP, 346-352 

overview, 253-254 

RADIO elements, 269-274 

SELECT elements, 274-277 

sending e-mail from, 616-618 

TEXT and TEXTAREA elements, 264-267 

variable formatting, 106-108 

variable passing, 100 

Venn diagrams, 792 

XML, 665-666 
formulaic writes, 577 
fpassthru function, 396-398, 402 
fputs function, 398 
fractal images, 703-710 
fractall.php file, 705-709 
Frameset page, 642 
fread function, 396-397 
free function, 574 

French Revolutionary calendar, 407 

fseek function, 402 

fsockopen function, 404 

ftell function, 402 

FTP connections, 395 

full-page images, 701-702 

full table scans, 283 

func_get_arg function, 443, 446 

func_get_args function, 443, 446-447 

func_num_args function, 443, 446 
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function keyword, 86 
function names, variables as, 450 
function not found error, 672 
functions, 60, 83 
accessor, 354 

arguments. See arguments and parameters 

C language, 796 

call-by-reference, 448-450 

call-by-value, 447-448 

cipher substitution example, 450-454 

class, 328-329 

date and time, 405-407 

defined, 86 

definition syntax, 86-88 
documentation, 84-86 
DOM, 657-659 
escaping, 127-128 
exceptions, 93-94 
files, 392-393 
filesystems, 400-403 
gd, 700-701 
implementing, 458 
introspection, 334-337 
in maintainability, 531 
mathematical, 158-159, 470 
MySQL, 225-226, 232-234 
networks, 403-405 
Oracle, 580-584 
overriding, 322 
parent, 329 

PEAR, 573-574, 838-839 
Perl, 803-804 
PostgreSQL, 556-557 
problems, 176-178, 305-307 
recursive, 96-98 

regular expressions, 377, 383-385 
return values vs. side effects, 83-84 
returning arrays, 136 
reuse, 237, 537 
SAX, 663 
scope, 95-98 
sessions, 419-421 
SimpleXML, 665 
SQLite, 606-609 
strings. See strings 
tokenizing and parsing, 371-374 
undefined, 177 
variable scope, 43, 90-94 
fwrite function, 398-399 



G 

Game class, 746-753 
game_class.php file, 735, 746-753 
game_display_class.php file, 735-744 
game_parameters_class.php file, 753-755 
game_text_class.php file, 735, 744-746 
GameDisplay class, 735-744 
gameLostText function, 746 
GameParameters class, 753-755 
games. See Certainty Quiz 
_gameStateString function, 744 
GameText class, 744-746 
gameWonText function, 746 
gd toolkit, 695 

concepts, 697-699 

functions, 700-701 

image formats and browsers, 696 

installation, 696-697 
generalized test methods, 342-345 
generate_session_id function, 41 1 
$_GET array, 101-102, 110 
get_cat_header stored procedure, 595-596 
get_categories stored procedure, 583-584 
get_categories.sql stored procedure, 594-595 
get_child_classes function, 339 
get_class function, 335-336 
get_class_methods function, 336 
get_class_vars function, 335, 337 
get_day_of_week function, 542 
get_declared_classes function, 335, 338 
get_html_translation_table function, 386 
GET method, 100-102 
get_object_vars function, 335, 337 
get_parent_class function, 335-336, 338 
get_post_value function, 756 
get_session_value function, 734, 756 
GET-style URLs, 102-104 
getAll function, 574 
getAnswer function, 759 
getAnswerSpread function, 759 
getAnswerSpreadDebit function, 754 
getAssoc function, 574 
getBlueColor function, 736 
getCol function, 574 
getCorrectAnswers function, 749 
getCredit function, 748 
getCurrentQuestion function, 748 
getCurrentQuestionText function, 749 
getdate function, 290, 406 
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getDbConnection function 
Game, 749 

GameParameters, 755 
getFormNum function, 639 
getGame function, 736 
getGameLost function, 749 
getGameParameters function, 748 
getGameWon function, 749 
getHighScorePosted function, 736 
gethostbyaddr function, 404 
gethostbyname function, 404 
gethostbynamel function, 404 
getltems function, 572 
getltems.php fife, 571-573 
getLevel function, 748 
getMaximumCredit function, 754 
getMaximumLevel function, 754 
getMessage method, 628 
getmxrr function, 404 
getName function, 354 
getOne function, 574 
getPageTitle function, 736 
getPreviousQuestion function, 748 
getProperty function, 626 
getQuestion function, 759 
_getQuestionIdsAtLevel function, 751 
getQuestionsAskedAtLevel function, 748 
getQuestionsPerLevel function, 755 
getrandmax function, 160, 162 
getRating function, 354 
getRedColor function, 736 
getRightAnswerCredit function, 754 
getRow function, 574 
getScalingType function, 759 
getservbyname function, 405 
getservbyport function, 405 
getStartingCredit function, 754 
getStartingLevel function, 754 
getter functions, 354 
getTotalQuestions function, 748 
getTraceAsString function, 508 
gettype function, 435-436 
getValue function, 329 
getWrongAnswerDebit function, 754 
GIF format, 696 
global Apache settings, 489 
global arrays, 110 
global-level errors in Oracle, 581 
global scope 

constants, 44 

variables, 43, 90-92 
$GLOBALS array, 105 



gmdate function, 407 
gmmktime function, 407 
gmstrftime function, 408 
gnome -libxml2 parser, 657 
GNOME XML library, 487 
go-pear.php command, 834 
go-pear web site, 833 
gpc_order setting, 492 
GRANT statement 

MySQL, 209 

PostgreSQL, 555-556 
GRANT ALL PRIVILEGES statement, 211 
GRANT REPLICATE SLAVE statement, 215 
graphics, 689 

fractal images, 703-710 

gd for. See gd toolkit 

HTML, 690-694 

HTTP, 701-702 

options, 689-690 

problems, 710-711 

summary, 712 
greater than signs (>) 

anchor tags, 381-382 

comparison operators, 62-63, 157 

PHP mode, 30, 69 
Greenwich Mean Time, 405, 407 
Gregorian calendar, 407 
GROUP BY construct, 289 

H 

hackers, 472 

handleEntryForm function, 766-767 
handleHighScore function, 738-739 
handleTest function, 344 
hashes 

arrays as, 132-133 

MD5, 386-387 

Perl language, 803 
header_download.php file, 594-599 
header function, 110, 397, 428, 430 
header.inc file, 720 
headers 

columns, 242 

function documentation, 85 

images, 710-711 

problems, 430 

sending, 428-430 
headingElementBreak function, 348 
Hello World program, 28-29 
heredoc style, 55 

example, 543-544 

syntax, 116-117 
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hexadecimal numbers 

conversions, 459-460 

integers, 47 

reading, 457 
HexDec function, 459-460 
hidden variables, 411-412 
hiddenVariablesString function, 348 
hierarchical XML structures, 649 
_highScoreEligible function, 741-742 
_highScoreString function, 743 
hosts, missing, 166 
HREFs, 381, 385 
.htaccess file, 489-490 
HTML 

escaping from, 28-32 

forms. See forms and form handlers 

generating, 346-352 

graphics, 690-694 

linebreaks, 57 

PHP code in, 809-811 

PHP-compliance, 27 

PHP learning strategies, 811-814 

static, 11-12 

string functions, 385-386 

tables. See tables 

validators, 526 

weblogs, 722-724 

vs. XML, 647-650 
HTML-embeddedness, 5-7, 803 
HTML_ENTITIES constant, 386 
HTML mode 

branching in, 68-69 

included files, 532 

vs. PHP mode, 539-544 
HTML_SPECIAL_CHARs constant, 386 
HTML Tidy utility, 526 
HTML validator utility, 526 
htmlentities function, 386 
HtmlForm class, 346-348 
HtmlFormlnput class, 348 
HtmlFormSelect class, 349 
HtmlFormText class, 350 
HtmlFormTextArea class, 350-351 
htmlspecialchars function, 386, 473 
$HTTP_GET_VARS array, 110 
$HTTP_POST_VARS array, 106, 110 
HTTP protocol 

authentication, 429-430 

graphics, 701-702 

opening files, 394 



response codes, 515 

sending headers, 428-430 

as stateless protocol, 99-100, 410 
$HTTP_SERVER_VARS variable, 106 
httpd.conf file 

file writing, 399 

global settings, 489 

PHP extensions directive, 24 
huge data sets, Oracle for, 577 

I 

idem-potent usages, 102 
identical operator, 63, 157 
IEsetup function, 641 
if structures 

PEAR, 837-838 

PHP, 65-69 

summary, 81-82 
ignore_user_abort setting, 493, 495 
IIS log files, 516 
imagearc function, 784 
imagecircle function, 779, 784 
ImageColorAllocate function, 698-699, 784 
ImageCreate function, 698, 784 
ImageCreateTrueColor function, 698 
ImageDestroy function, 699, 784 
imageellipse function, 784 
ImageFill function, 784 
imagefontwidth function, 785 
imagePng function, 705, 784 
images. See graphics 
ImageString function, 784 
imagetojpeg function, 699 
imagetopng function, 699, 701 
<IMG> tag, 702 
immutable strings, 119 
implode function, 374, 440-441 
in_array function, 139 
in-query functions, 289 
include function, 30-31, 95-96, 173-174 
include_once function, 30-31, 96 
include_path directive, 31, 96, 493 
included files 

including, 30-32 

maintainability, 531-532 

missing, 173-174 

password, 723 

problems, 169 
increment operators, 155-156, 537 
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indentation in PEAR, 836-837 
index.php file 

Cartoons databases, 557-558, 560-562, 564-565 

Certainty Quiz, 732-735 
indexes 

array, 135-136 

limiting, 285-286 

overview, 282-283 

primary keys, 284-285 

strings, 115 

tradeoffs, 283 

UNIQUE INDEX clause, 286-287 
indivisible tokens, 35 
infinite loops, 79, 180 
informative variables, 529 
inheritance, 315-316, 320-321, 355 
ini_set statement, 627 
$initial_entry_date variable, 717 
initial expressions in for statements, 73 
inner joins, 198 
INPUT statement, 106 
inputFormsString function, 347-348 
Insecure. Org site, 480 
insert. php file, 558-560 
INSERT statement 

indexing, 283 

PostgreSQL, 555 

SQL, 200 
inserting data in SQLite, 608 
inspecting 

arrays, 139 

strings, 118 
installation 

gd toolkit, 696-697 

MySQL, 189-191 

PHP, 19-20 

development tools, 26-27 
problems, 165-166 
procedures, 20-26 
_installQuestion function, 749-750 
instances, 314 

creating, 319 

OOP, 316 
INT data type, 230-231 
INTEGER data type, 231 
integers, 47, 153 

C language, 796 

conversions with, 436-437, 440 
largest, 442 
MySQL, 230-231 
overflow, 441 
primary keys, 284 



testing for, 436 

type contagion, 155 
interfaces, OOP, 327 
internal DTDs, 653 
international PHP development, 822 
internationalization, 662 
Internet Information Server (IIS), 7, 25 
interpolation 

strings, 114-115 

variables, 54, 304, 802 
intersecting circles area, 773-776 
intersection_label function, 783 
introduction function, 745 
introspection functions, 317, 334-337 
intval function, 154, 437 
IP addresses for sessions, 411 
iptables firewall, 22 
is_ functions, 436 
is_array function, 139 
Is_dir function, 402 
Is_executable function, 402 
Is_file function, 402 
is_finite function, 457 
is_float function, 457 
is_infinite function, 457 
is_int function, 393, 457 
Is_link function, 402 
is_long function, 457 
is_nan function, 179, 457 
is_numeric function, 393, 456-457 
Is_readable function, 402 
is_subclass_of function, 335 
is_valid_user function, 498-500, 503 
is_writable function, 402 
isError function, 570, 573 
ISO-8859-1 encodings, 662 
isolation in debugging, 512 
isset function, 42, 51, 139 
isWarning function, 573 
iterations 

current and next, 143-145 

each, 147-149 

foreach, 142-143 

function summary, 150-151 

reset, 145-146 

reverse order, 146 

support, 140-142 

walking, 149 

J 

java.awt* packages, 629 

Java Development Kit (JDK) environment, 624 
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JAVA_HOME setting, 624 
java.lang. System file, 625 
Java language, 619 
applets, 13 

configuration option, 487 
errors and exceptions, 627-628 
extension, 623-625 
Java object, 625-627 
Java Server Pages, 621-622 
PHP differences, 620-621 
PHP similarities, 620 
problems, 628 
SAP1, 623 
summary, 629 
uses, 629 

java_last_exception_clear function, 627 
java_last_exception_get function, 627 
java.library variable, 624 
java.library.path variable, 624 
Java object, 625-627 
Java Server Pages (JSP), 621-622 
javadoc tool, 528 
JavaScript language, 631 

dynamic, 636-642 

outputting, 631-634 

passing data to PHP, 642-645 

PHP as backup for, 634-635 

static, 636 

summary, 646 
javatest.php file, 625 
JDDayofWeek function, 408 
JDK (Java Development Kit) environment, 624 
JDMonthName function, 408 
jmp function, 639 
joins, 196-198 
jpeg-6b library, 697 
JPEG format, 696 
Julian Date, 407-408 
jumping in and out of PHP mode, 30 

K 

key function, 147 

keys and values in arrays, 132, 134-135 

current, 141 

empty, 147-149 

extracting, 147 

retrieving, 358-359 
keyword case-sensitivity, 491 
knowledgebase, 824-825 
krsort function, 367 
ksort function, 367 
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labels in heredoc syntax, 116 
LAMP stack, 4 
largest integer, 442 

last-in-first-out (LIFO) containers, 363 

last inserted row, finding, 291-292 

late binding, 317 

Latinl encoding, 662 

left Jabel function, 782-783 

left outer joins, 199 

legal liability, Oracle for, 577 

length of strings, 55, 115, 118 

LengthException class, 503 

less than signs (<) 

anchor tags, 381 

comparisons, 62, 157 

heredoc syntax, 116 

PHP mode, 30, 69 
letter_cipher function, 451-452 
levenshtein function, 389 
Levenshtein metric, 389 
Libby, Dan, 9 
libjpeg library, 487 
libmcrypt library, 487 
libphp6.so file, 623 
libpng library, 697 
libraries in Java, 620 
libxml library, 23 
libxml validator, 655 
libxml2-devel package, 23 
libxml2 parser, 655, 660 
line-drawing functions, 700 
line length in PEAR, 836-837 
line segments in fractal images, 704 
linebreaks in HTML, 57 
link function, 402 
link-scraper example, 381-382 
hnked-list pointer system, 141 
linkinfo function, 402 
linking C language, 798 
Linux 

e-mail configuration, 614 
MySQL Server installation on, 190 
PEAR Package Manager on, 832-833 
PHP installation on, 22 
list construct, 136-137, 803 
loading page problems, 168-169 
LoadModule setting, 491 
loads from Web services, 681 
local development in MySQL, 211 
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